From a78106833594c1c2583e3f77427f12bc166c13ff Mon Sep 17 00:00:00 2001 From: Seth Boyles Date: Tue, 23 Sep 2025 10:38:02 -0700 Subject: [PATCH 1/5] Add docs for Registry Credentials --- deploy-apps/push-docker.html.md.erb | 8 ++ deploy-apps/registry-credentials.html.md.erb | 135 +++++++++++++++++++ index.html.md.erb | 1 + 3 files changed, 144 insertions(+) create mode 100644 deploy-apps/registry-credentials.html.md.erb diff --git a/deploy-apps/push-docker.html.md.erb b/deploy-apps/push-docker.html.md.erb index 184da041..e4f1cb34 100644 --- a/deploy-apps/push-docker.html.md.erb +++ b/deploy-apps/push-docker.html.md.erb @@ -164,6 +164,14 @@ Apps require access to the container registry when starting. If you do not update the app with the new credentials, <%= vars.app_runtime_abbr %> fails to start the app. When you rotate container credentials, <%= vars.recommended_by %> recommends using a set of two credentials, where the old credentials can be deactivated after all apps are pushed with the new credentials. +### Basic Authentication with stored Registry Credentials + +Admins, Org Manager, and Space Developers can store Docker registry credentials for reuse among developers using Registry Credentials. + +When using Registry Credentials, apps can use the stored credentials instead of requiring credentials on each push. + +Please see [Using stored Registry Credentials to push Docker apps](registry-credentials.html) for more information. + ### Amazon Elastic Container Registry (ECR) <%= vars.app_runtime_abbr %> supports pushing apps from images hosted on Amazon Web Services ECR, which authenticates with temporary password tokens. diff --git a/deploy-apps/registry-credentials.html.md.erb b/deploy-apps/registry-credentials.html.md.erb new file mode 100644 index 00000000..057044a7 --- /dev/null +++ b/deploy-apps/registry-credentials.html.md.erb @@ -0,0 +1,135 @@ +--- +title: Using stored Registry Credentials to push Docker apps +owner: CAPI +--- + +Registry Credentials provide a way to share Docker registry credentials across a foundation, organization, or space. Without using Registry Credentials, credentials must be provided for every push when trying to push with an image from a private registry: + +``` +CF_DOCKER_PASSWORD=PASSWORD cf push APP-NAME --docker-image REPO/IMAGE:TAG --docker-username USER +``` + +By creating Registry Credentials, Admins, Org Managers, and Space Developers can save Docker credentials for reuse among developers. + +Registry Credentials can be created at four different levelsds: + +* Foundation +* Organization +* Space +* App + +For example, an Org Manager can create a Registry Credential for an Organization, which will be available to all Apps within that Organization: + +``` +cf target -o ORG +CF_DOCKER_PASSWORD=PASSWORD cf create-org-registry-credential REGISTRY-LOCATION --username USER +``` + +After the Registry Credential is created, Space Developers can push apps referencing images in the private registry without providing credentials: + +``` +cf push APP-NAME --docker-image REGISTRY-LOCATION/REPO/IMAGE:TAG +``` + +## Creating Registry Credentials for a Foundation, Organization, or Space + +Registry Credentials can be created for a Foundation, Organization, or Space using the `cf create-foundation-registry-credential`, `cf create-org-registry-credential`, or `cf create-space-registry-credential` commands. + +For example, an Admin can create a Registry Credential for the Foundation: + +``` +cf create-foundation-registry-credential REGISTRY-LOCATION --username USER +``` + +The password for the Registry Credential can be provided using the `CF_DOCKER_PASSWORD` environment variable. If the environment variable is not set, users will be prompted for the password. + +- **Foundation-scoped Registry Credentials** are available to all Apps on the platform and can only be created or altered by an Admin. +- **Organization-scoped Registry Credentials** are available to Apps within the Organization and can only be created or altered by an Org Manager or Admin. +- **Space-scoped Registry Credentials** are available to all Apps within the Space and can be created or altered by a Space Developer, Org Manager, or Admin. + +The `create-org-registry-credential` and `create-space-registry-credential` commands are context sensitive and will create Registry Credentials for the Organization or Space that the user is currently targeting. + +`REGISTRY-LOCATION` must include a hostname and may include paths and/or ports. (e.g. `registry.example.com`, `registry.example.com/path`, `registry.example.com/path/to/repo:5000`). Protocols such as `https://` must not be included. + +## Creating Registry Credentials for an app + +If an App is pushed with Docker credentials provided, an App-scoped Registry Credential is created automatically for the App, allowing future pushes to omit credentials. + +This Registry Credential is only available to the App and cannot be shared with other Apps, and will take precedence over any other Registry Credential for that particular private registry. + +Providing new credentials on future pushes will update the App-scoped Registry Credential. + +App-scoped Registry Credentials will only be created or updated during the 'start' phase of the push. If a push fails during staging (potentially due to incorrect credentials), for example, the App-scoped Registry Credential will not be created. + +## Using Registry Credentials + +When pushing an app, Cloud Foundry determines the Registry Credential to use by the following precedence: + +1. App-scoped Registry Credential +1. Space-scoped Registry Credential +1. Organization-scoped Registry Credential +1. Foundation-scoped Registry Credential + +Among each level, Cloud Foundry will extract the Registry Location from the image reference and attempt to find a matching Registry Credential, preferring more specific matches. + +For example, if an App is pushed with the image reference `registry.example.com/repo/image:tag`, Cloud Foundry will first check for App-scoped Registry Credentials in the following order: + +1. `registry.example.com/repo` +1. `registry.example.com` +1. `example.com` + +If no App-scoped Registry Credential is found, Cloud Foundry will perform the same search for Space-scoped Registry Credentials, then Organization-scoped Registry Credentials, and finally Foundation-scoped Registry Credentials. + +If no matching Registry Credential is found, Cloud Foundry will still attempt to stage and start the app for cases where the image is publically accessible. + +Images references of the form `REPO/IMAGE:TAG` (i.e. with no registry hostname) will search for Registry Credentials for `docker.io/libary` or `docker.io`. + +## Deleting Registry Credentials + +Registry Credentials can be deleted using the appropriate command: + +``` +cf delete-foundation-registry-credential REGISTRY-LOCATION +cf delete-org-registry-credential REGISTRY-LOCATION +cf delete-space-registry-credential REGISTRY-LOCATION +cf delete-app-registry-credential REGISTRY-LOCATION APP-NAME +``` + +Deleting a Registry Credential will cause any apps that were pushed with that Registry Credential to fail to stage and start in the future, unless other Registry Credentials are made available to them. + +## Updating Registry Credentials + +Registry Credentials can be updated using the appropriate command: + +``` +cf update-foundation-registry-credential REGISTRY-LOCATION --username USER +cf update-org-registry-credential REGISTRY-LOCATION --username USER +cf update-space-registry-credential REGISTRY-LOCATION --username USER +``` + +App-scoped Registry Credentials can be updated by pushing the app with new credentials: + +``` +cf push APP-NAME --docker-image REGISTRY-LOCATION/REPO/IMAGE:TAG --docker-username USER +``` + +Like the creation commands, the password for the Registry Credential can be provided using the `CF_DOCKER_PASSWORD` environment variable. If the environment variable is not set, users will be prompted for the password. + +Only username or password may be updated--the registry location cannot be changed. + +## Listing Registry Credentials + +All Registry Credentials available to the currently targeted Organization and Space can be listed with the `cf registry-credentials` command: + +``` +$ cf registry-credentials +Showing registry credentials available to org 'myorg' and space 'myspace'... +location scope username app name +docker.io/library app myuser myapp +registry.example.com space spaceuser +registry.example.com/repo organization orguser +docker.io/libary foundation docker-user +registry.example.com/repo foundation private-repo-user +``` + +If no space or organization is targeted, only Registry Credentials available to the foundation will be listed. \ No newline at end of file diff --git a/index.html.md.erb b/index.html.md.erb index 96fe00a1..284d714c 100644 --- a/index.html.md.erb +++ b/index.html.md.erb @@ -29,6 +29,7 @@ If you do these things, you are a <%= vars.app_runtime_abbr %> **developer**, a * [Deploying with app manifests](deploy-apps/manifest.html) * [App manifest attribute reference](deploy-apps/manifest-attributes.html) * [Deploying your app with Docker](deploy-apps/push-docker.html) + * [Using shared Registry Credentials for Docker apps](deploy-apps/registry-credentials.html) * [Deploying your large apps](deploy-apps/large-app-deploy.html) * [Starting, restarting, and restaging apps](deploy-apps/start-restart-restage.html) * [Pushing an app with multiple processes](multiple-processes.html) From 31716970655ab93cfe5dd097f340162985b3b4a3 Mon Sep 17 00:00:00 2001 From: Anita Flegg Date: Tue, 23 Sep 2025 12:44:45 -0700 Subject: [PATCH 2/5] Minor editorial changes --- deploy-apps/push-docker.html.md.erb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/deploy-apps/push-docker.html.md.erb b/deploy-apps/push-docker.html.md.erb index e4f1cb34..ccfa49d9 100644 --- a/deploy-apps/push-docker.html.md.erb +++ b/deploy-apps/push-docker.html.md.erb @@ -166,11 +166,11 @@ When you rotate container credentials, <%= vars.recommended_by %> recommends usi ### Basic Authentication with stored Registry Credentials -Admins, Org Manager, and Space Developers can store Docker registry credentials for reuse among developers using Registry Credentials. +Admins, Org Managers, and Space Developers can store Docker registry credentials for reuse among developers using Registry Credentials. When using Registry Credentials, apps can use the stored credentials instead of requiring credentials on each push. -Please see [Using stored Registry Credentials to push Docker apps](registry-credentials.html) for more information. +For more information, see [Using stored Registry Credentials to push Docker apps](registry-credentials.html). ### Amazon Elastic Container Registry (ECR) From 713d7f5f5c2534ce8853649b46192a6366eabc1a Mon Sep 17 00:00:00 2001 From: Anita Flegg Date: Tue, 23 Sep 2025 13:10:00 -0700 Subject: [PATCH 3/5] various VMware style edits --- deploy-apps/registry-credentials.html.md.erb | 32 ++++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/deploy-apps/registry-credentials.html.md.erb b/deploy-apps/registry-credentials.html.md.erb index 057044a7..e1ca25bf 100644 --- a/deploy-apps/registry-credentials.html.md.erb +++ b/deploy-apps/registry-credentials.html.md.erb @@ -11,7 +11,7 @@ CF_DOCKER_PASSWORD=PASSWORD cf push APP-NAME --docker-image REPO/IMAGE:TAG --doc By creating Registry Credentials, Admins, Org Managers, and Space Developers can save Docker credentials for reuse among developers. -Registry Credentials can be created at four different levelsds: +Registry Credentials can be created at four different levels: * Foundation * Organization @@ -41,25 +41,25 @@ For example, an Admin can create a Registry Credential for the Foundation: cf create-foundation-registry-credential REGISTRY-LOCATION --username USER ``` -The password for the Registry Credential can be provided using the `CF_DOCKER_PASSWORD` environment variable. If the environment variable is not set, users will be prompted for the password. +The password for the Registry Credential can be provided using the `CF_DOCKER_PASSWORD` environment variable. If the environment variable is not set, users are prompted for the password. - **Foundation-scoped Registry Credentials** are available to all Apps on the platform and can only be created or altered by an Admin. - **Organization-scoped Registry Credentials** are available to Apps within the Organization and can only be created or altered by an Org Manager or Admin. - **Space-scoped Registry Credentials** are available to all Apps within the Space and can be created or altered by a Space Developer, Org Manager, or Admin. -The `create-org-registry-credential` and `create-space-registry-credential` commands are context sensitive and will create Registry Credentials for the Organization or Space that the user is currently targeting. +The `create-org-registry-credential` and `create-space-registry-credential` commands are context sensitive and create Registry Credentials for the Organization or Space that the user is currently targeting. -`REGISTRY-LOCATION` must include a hostname and may include paths and/or ports. (e.g. `registry.example.com`, `registry.example.com/path`, `registry.example.com/path/to/repo:5000`). Protocols such as `https://` must not be included. +`REGISTRY-LOCATION` must include a host name, and may include paths and/or ports; for example, `registry.example.com`, `registry.example.com/path`, `registry.example.com/path/to/repo:5000`. Protocols such as `https://` must not be included. ## Creating Registry Credentials for an app If an App is pushed with Docker credentials provided, an App-scoped Registry Credential is created automatically for the App, allowing future pushes to omit credentials. -This Registry Credential is only available to the App and cannot be shared with other Apps, and will take precedence over any other Registry Credential for that particular private registry. +This Registry Credential is only available to the App and cannot be shared with other Apps; it takes precedence over any other Registry Credential for that particular private registry. -Providing new credentials on future pushes will update the App-scoped Registry Credential. +Providing new credentials on future pushes updates the App-scoped Registry Credential. -App-scoped Registry Credentials will only be created or updated during the 'start' phase of the push. If a push fails during staging (potentially due to incorrect credentials), for example, the App-scoped Registry Credential will not be created. +App-scoped Registry Credentials are only created or updated during the 'start' phase of the push. If a push fails during staging (potentially due to incorrect credentials), for example, the App-scoped Registry Credential is not created. ## Using Registry Credentials @@ -70,19 +70,19 @@ When pushing an app, Cloud Foundry determines the Registry Credential to use by 1. Organization-scoped Registry Credential 1. Foundation-scoped Registry Credential -Among each level, Cloud Foundry will extract the Registry Location from the image reference and attempt to find a matching Registry Credential, preferring more specific matches. +Among each level, Cloud Foundry extracts the Registry Location from the image reference and attempts to find a matching Registry Credential, preferring more specific matches. -For example, if an App is pushed with the image reference `registry.example.com/repo/image:tag`, Cloud Foundry will first check for App-scoped Registry Credentials in the following order: +For example, if an App is pushed with the image reference `registry.example.com/repo/image:tag`, Cloud Foundry first checks for App-scoped Registry Credentials in the following order: 1. `registry.example.com/repo` 1. `registry.example.com` 1. `example.com` -If no App-scoped Registry Credential is found, Cloud Foundry will perform the same search for Space-scoped Registry Credentials, then Organization-scoped Registry Credentials, and finally Foundation-scoped Registry Credentials. +If no App-scoped Registry Credential is found, Cloud Foundry performs the same search for Space-scoped Registry Credentials, then Organization-scoped Registry Credentials, and finally, Foundation-scoped Registry Credentials. -If no matching Registry Credential is found, Cloud Foundry will still attempt to stage and start the app for cases where the image is publically accessible. +If no matching Registry Credential is found, Cloud Foundry still attempts to stage and start the app for cases in which the image is publically accessible. -Images references of the form `REPO/IMAGE:TAG` (i.e. with no registry hostname) will search for Registry Credentials for `docker.io/libary` or `docker.io`. +Images references of the form `REPO/IMAGE:TAG` (i.e. with no registry hostname) search for Registry Credentials for `docker.io/libary` or `docker.io`. ## Deleting Registry Credentials @@ -95,7 +95,7 @@ cf delete-space-registry-credential REGISTRY-LOCATION cf delete-app-registry-credential REGISTRY-LOCATION APP-NAME ``` -Deleting a Registry Credential will cause any apps that were pushed with that Registry Credential to fail to stage and start in the future, unless other Registry Credentials are made available to them. +Deleting a Registry Credential causes any apps that were pushed with that Registry Credential to fail to stage and start in the future, unless other Registry Credentials are made available to them. ## Updating Registry Credentials @@ -113,9 +113,9 @@ App-scoped Registry Credentials can be updated by pushing the app with new crede cf push APP-NAME --docker-image REGISTRY-LOCATION/REPO/IMAGE:TAG --docker-username USER ``` -Like the creation commands, the password for the Registry Credential can be provided using the `CF_DOCKER_PASSWORD` environment variable. If the environment variable is not set, users will be prompted for the password. +Like the creation commands, the password for the Registry Credential can be provided using the `CF_DOCKER_PASSWORD` environment variable. If the environment variable is not set, users are prompted for the password. -Only username or password may be updated--the registry location cannot be changed. +Only username or password may be updated; the registry location cannot be changed. ## Listing Registry Credentials @@ -132,4 +132,4 @@ docker.io/libary foundation docker-user registry.example.com/repo foundation private-repo-user ``` -If no space or organization is targeted, only Registry Credentials available to the foundation will be listed. \ No newline at end of file +If no space or organization is targeted, only Registry Credentials available to the foundation are listed. From 7f01525367e171031958922d40b8e374df55a62d Mon Sep 17 00:00:00 2001 From: Seth Boyles Date: Wed, 24 Sep 2025 13:34:43 -0700 Subject: [PATCH 4/5] Address comments --- deploy-apps/registry-credentials.html.md.erb | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/deploy-apps/registry-credentials.html.md.erb b/deploy-apps/registry-credentials.html.md.erb index e1ca25bf..340a0fb0 100644 --- a/deploy-apps/registry-credentials.html.md.erb +++ b/deploy-apps/registry-credentials.html.md.erb @@ -47,7 +47,12 @@ The password for the Registry Credential can be provided using the `CF_DOCKER_PA - **Organization-scoped Registry Credentials** are available to Apps within the Organization and can only be created or altered by an Org Manager or Admin. - **Space-scoped Registry Credentials** are available to all Apps within the Space and can be created or altered by a Space Developer, Org Manager, or Admin. -The `create-org-registry-credential` and `create-space-registry-credential` commands are context sensitive and create Registry Credentials for the Organization or Space that the user is currently targeting. +The `create-org-registry-credential` and `create-space-registry-credential` commands are context sensitive and create Registry Credentials for the Organization or Space that the user is currently targeting. For example, to create a Space-scoped Registry Credential, the user must target the Space first: + +``` +cf target -o ORG -s SPACE +cf create-space-registry-credential REGISTRY-LOCATION --username USER +``` `REGISTRY-LOCATION` must include a host name, and may include paths and/or ports; for example, `registry.example.com`, `registry.example.com/path`, `registry.example.com/path/to/repo:5000`. Protocols such as `https://` must not be included. @@ -63,26 +68,26 @@ App-scoped Registry Credentials are only created or updated during the 'start' p ## Using Registry Credentials -When pushing an app, Cloud Foundry determines the Registry Credential to use by the following precedence: +When pushing an app, the Registry Credential is selected by the following order of precedence: 1. App-scoped Registry Credential 1. Space-scoped Registry Credential 1. Organization-scoped Registry Credential 1. Foundation-scoped Registry Credential -Among each level, Cloud Foundry extracts the Registry Location from the image reference and attempts to find a matching Registry Credential, preferring more specific matches. +Among each level, the Registry Location is extracted from the image reference and used to find a possible matching Registry Credentials. More specific matches are preferred. -For example, if an App is pushed with the image reference `registry.example.com/repo/image:tag`, Cloud Foundry first checks for App-scoped Registry Credentials in the following order: +For example, if an App is pushed with the image reference `registry.example.com/repo/image:tag`, App-scoped Registry Credentials are searched for in the following order: 1. `registry.example.com/repo` 1. `registry.example.com` 1. `example.com` -If no App-scoped Registry Credential is found, Cloud Foundry performs the same search for Space-scoped Registry Credentials, then Organization-scoped Registry Credentials, and finally, Foundation-scoped Registry Credentials. +If no App-scoped Registry Credential is found, the same search is performed for Space-scoped Registry Credentials, then Organization-scoped Registry Credentials, and finally, Foundation-scoped Registry Credentials. -If no matching Registry Credential is found, Cloud Foundry still attempts to stage and start the app for cases in which the image is publically accessible. +If no matching Registry Credential is found, the app push continues as normal, in case the image is publically accessible. -Images references of the form `REPO/IMAGE:TAG` (i.e. with no registry hostname) search for Registry Credentials for `docker.io/libary` or `docker.io`. +Images references of the form `REPO/IMAGE:TAG` (i.e. with no registry host name) search for Registry Credentials for `docker.io/libary` or `docker.io`. ## Deleting Registry Credentials From b24b08cbe6167ddef9b968c4c868557836970453 Mon Sep 17 00:00:00 2001 From: Seth Boyles Date: Wed, 24 Sep 2025 21:06:06 -0700 Subject: [PATCH 5/5] OrgManagers cannot create/edit space credentials --- deploy-apps/registry-credentials.html.md.erb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-apps/registry-credentials.html.md.erb b/deploy-apps/registry-credentials.html.md.erb index 340a0fb0..9d3b3d83 100644 --- a/deploy-apps/registry-credentials.html.md.erb +++ b/deploy-apps/registry-credentials.html.md.erb @@ -45,7 +45,7 @@ The password for the Registry Credential can be provided using the `CF_DOCKER_PA - **Foundation-scoped Registry Credentials** are available to all Apps on the platform and can only be created or altered by an Admin. - **Organization-scoped Registry Credentials** are available to Apps within the Organization and can only be created or altered by an Org Manager or Admin. -- **Space-scoped Registry Credentials** are available to all Apps within the Space and can be created or altered by a Space Developer, Org Manager, or Admin. +- **Space-scoped Registry Credentials** are available to all Apps within the Space and can be created or altered by a Space Developer or Admin. The `create-org-registry-credential` and `create-space-registry-credential` commands are context sensitive and create Registry Credentials for the Organization or Space that the user is currently targeting. For example, to create a Space-scoped Registry Credential, the user must target the Space first: