Document URL: https://docs.openshift.com/enterprise/3.1/creating_images/index.html Section Number and Name: NOT Defined Describe the issue: The project name MUST appear in the docker tag to check an image into the internal docker registry. This is not documented. Suggestions for improvement: Define a new section that outlines adding images to the internal docker registry for use.
Since the docs already include quite a bit of information on the internal registry: https://docs.openshift.com/enterprise/3.1/install_config/install/docker_registry.html i plan to simply link to that information from the Overview section: https://docs.openshift.com/enterprise/3.1/creating_images/index.html Turning to the other registry-related point, i have some questions about the need to reboot. (a) Is the reboot needed due to registry change, or due to some other reason? (b) Are there other circumstances that would require reboot? (IOW, should we document the need to reboot solely in the context of changing the registry, or would it be better to document it at a wider scope?) Adding Eric as needinfo, for these questions. Any other reboot-related information would be welcome, too.
I am in aware of what or why you would need to reboot however I feel it's because of a change to the master config. I would check with engineering and we to be sure we have a test case for the use case we are documenting and confirm if a reebot is needed.
Unless there are strong objections, i would like to reduce the scope of this BZ to the xref described in comment #3. IMHO documenting the need to reboot the cluster when the registry changes is like documenting the need to reboot a single machine when the kernel changes: It seems too obvious!
My understanding has changed on whether or not to explicitly mention a cluster reboot. Before, i was thinking only of the end user. Now, thanks to Eric and Vikram, i understand that the explicit documentation of the requirement for a cluster reboot after significant registry change is useful when the documentation is to be used in an on-sell context. So, for this, i will add an "IMPORTANT" admonition to the section "Storage for the Registry", because i believe that is the only significant registry change that would require a reboot. To check this assumption, i have question for Andy Goldstein: Are there any other significant registry changes that would require a reboot?
Re "project name MUST appear in docker tag", there is already an "IMPORTANT" admonition in the section "Pushing and Pulling Images" which says: You can pull arbitrary images, but if you have the system:registry role added, you can only push images to the registry in your project. I propose to extend this with the statement: Furthermore, the project name *must* appear in the tag for OpenShift to correctly place and later access the image in the registry. Andy, does that sound reasonable? Are there any exceptions or corner cases we should mention?
You do not need to reboot the entire cluster if you delete and recreate the integrated registry. We have a limitation currently where the integrated registry is referenced by IP address in image streams and Docker image pull specifications. We hope to change this to a DNS name in the future [1]. Until that happens, if you decide to delete and recreate the docker-registry service, you should make every effort to reuse the IP address it was originally assigned [2]. If you aren't able to reuse the IP address, the only component you need to reboot is the master. In this case, however, anything in etcd that has a reference to the previous IP address will continue to have that reference, meaning it will point to an invalid location. Re "Furthermore, the project name *must* appear in the tag for OpenShift to correctly place and later access the image in the registry.", it's not the tag where the name must appear. It must be part of the image's name. For example, if my project is "andy" and my image stream name is "webapp", then I would need to do this to be able to push it to the integrated registry: docker tag someimage $registry/andy/webapp:latest where $registry is either the publicly available route for the registry, or the docker-registry service's IP address (if I'm running this on a master or node). "latest" is the tag and can be whatever the user wants to use. [1] https://trello.com/c/Q1oYRFax/21-configure-node-s-resolv-conf-to-use-skydns-from-master [2] https://github.com/openshift/openshift-docs/issues/1494
(In reply to Andy Goldstein from comment #9) > [...] if you decide to delete and recreate the docker-registry > service, you should make every effort to reuse the IP address it was > originally assigned [2]. > > If you aren't able to reuse the IP address, the only component you need to > reboot is the master. In this case, however, anything in etcd that has a > reference to the previous IP address will continue to have that reference, > meaning it will point to an invalid location. It sounds like the generally safe thing to do if the IP addr DOES change is to reboot the cluster. Or is there some kind of ‘sed -i’ for the entire etcd store? That strikes me as kludgy approach anyway...
(In reply to Thien-Thi Nguyen from comment #10) > > It sounds like the generally safe thing to do if the IP addr DOES change is > to reboot the cluster. Or is there some kind of ‘sed -i’ for the entire > etcd store? That strikes me as kludgy approach anyway... There is no benefit to rebooting the entire cluster. I would strongly advise against it. Just restart the masters. It would be nice to be able to update all image pull specs in etcd to use the new address. Maybe we'll add that capability sometime (I assume we'll need it when we switch from IP to DNS).
(In reply to Andy Goldstein from comment #11) > There is no benefit to rebooting the entire cluster. > I would strongly advise against it. Just restart the masters. IIUC you're saying that it's no problem (neither immediate nor latent) to have dangling references in etcd. Maybe i'm just old-fashioned, but just the thought of this gives me the heebie-jeebies... To turn things around, here's another question: Are there any grave consequences to rebooting the entire cluster? (Or: Why do you strongly advise against it?) Presumably, changing the docker-registry service is a Serious Act, so some associated extra downtime would be unsurprising. > It would be nice to be able to update all image pull specs in etcd to use > the new address. Maybe we'll add that capability sometime (I assume we'll > need it when we switch from IP to DNS). To move ahead on the other uncontroversial bits, i have gone ahead and created: https://github.com/openshift/openshift-docs/pull/1638 It includes "reboot"-related changes, but based on the current discussion, i expect that we will need to refine it a bit. BTW, thanks for the pointer to issue 1494.
(In reply to Thien-Thi Nguyen from comment #12) > (In reply to Andy Goldstein from comment #11) > > There is no benefit to rebooting the entire cluster. > > I would strongly advise against it. Just restart the masters. > > IIUC you're saying that it's no problem (neither immediate nor latent) to > have dangling references in etcd. Maybe i'm just old-fashioned, but just > the thought of this gives me the heebie-jeebies... That's not what I'm saying. It is not a good thing to have dangling references in etcd. We ultimately want to make that possibility go away. In the meantime, however, the only part of the cluster that needs to be restarted if the URL (read: IP address today) of the docker-registry service changes is the master api. That component caches the registry's URL, hence the need to restart. If you restart anything else, you're risking an outage somewhere. If you restart a node, all of the pods on that node are offline while the node is rebooting. That's why I'm saying rebooting everything is unnecessary. > To turn things around, here's another question: Are there any grave > consequences to rebooting the entire cluster? (Or: Why do you strongly > advise against it?) Presumably, changing the docker-registry service is a > Serious Act, so some associated extra downtime would be unsurprising. As mentioned above, you'll be taking pods offline. > > > It would be nice to be able to update all image pull specs in etcd to use > > the new address. Maybe we'll add that capability sometime (I assume we'll > > need it when we switch from IP to DNS). > > To move ahead on the other uncontroversial bits, i have gone ahead and > created: > > https://github.com/openshift/openshift-docs/pull/1638 > > It includes "reboot"-related changes, but based on the current discussion, i > expect that we will need to refine it a bit. BTW, thanks for the pointer to > issue 1494. Comments added to the gh pr.
PR merged. Moving status to RELEASE_PENDING.
Verified live: - https://docs.openshift.com/enterprise/3.1/architecture/core_concepts/builds_and_image_streams.html#referencing-images-in-image-streams - https://docs.openshift.com/enterprise/3.1/creating_images/index.html - https://docs.openshift.com/enterprise/3.1/install_config/install/docker_registry.html#maintaining-the-registry-ip-address Moving status to CLOSED CURRENTRELEASE.