docs: Image Pull Secret Doc

docs/user-guide/global-configurations/docker-registries.md

@@ -1,43 +1,52 @@
 # Container Registries
 
-Container registries are used to store images built by the CI Pipeline. Here you can configure the container registry you want to use for storing images.
+Container registries are used for storing images built by the CI Pipeline. You can configure the container registry using any different container registry provider of your choice. It allows you to build, deploy and manage your container images with easy-to-use UI. 
 
-When configuring an application, you can choose which registry and repository it should use in the App Configuration > [Docker Build Config](../creating-application/deployment-template.md) section.
+When configuring an application, you can choose the specific container registry and repository in the App Configuration > [Build Configuration](user-guide/creating-application/docker-build-configuration.md) section.
 
-## Add Container Registry configuration:
+Provide the information in the following fields to configure the container registry from App Configuration > [Build Configuration](user-guide/creating-application/docker-build-configuration.md) section.
 
-Go to the `Container Registry` section of `Global Configuration`. Click on `Add container registry`.
+| Fields | Description |
+| --- | --- |
+| **Container Registry** | Select the container registry from the drop-down list. |
+| **Container Repository** | Enter the name of the container repository. |
 
-You will see below the input fields to configure the container registry.
 
-* Name
-* Registry type
-  * ecr
-    * AWS region
-    * Access key ID
-    * Secret access key
-  * docker hub
-    * Username
-    * Password
-  * Others
-    * Username
-    * password
-* Registry URL
-* Set as default
+## Add Container Registry:
 
-![](../../user-guide/global-configurations/images/Container_Registry.jpg)
+To add container registry, go to the `Container Registry` section of `Global Configurations`. Click **Add Container Registry**.
 
-### Name
+| Fields | Description |
+| --- | --- |
+| **Name** | Provide a name to your registry, this name will be shown to you in Build Configuration in the drop-down list. |
+| **Registry Type** | Select the registry type from the drop-down list. E.g., Docker. |
+| **Registry URL** | Provide the URL of your registry. |
+| **Set as default registry** | Enable this field to set as default registry hub for your images. |
 
-Provide a name to your registry, this name will be shown to you in Docker Build Config as a drop-down.
+* For each **Registry Type**, the credential input fields are different. Please see the table below to know the required credential inputs as per the selected registry type.
 
-### Registry type
+| Registry Type | Credentials |
+| --- | --- |
+| **ECR** | Select one of the authentication types:<ul><li>**EC2 IAM Role**</li></ul> <ul><li>**User Auth**<ul><li>`Access key ID`: </li></ul><ul><li>`Secret access key`</li></ul></li></ul>|
+| **Docker** | <ul><li>`Username`</li></ul> <ul><li>`Password/Token (Recommended:Token)`</li></ul> |
+| **Azure**  | <ul><li>`Username/Registry Name`</li></ul> <ul><li>`Password`</li></ul>  |
+| **Artifact Registry (GCP)**  | <ul><li>`Username`</li></ul> <ul><li>`Service Account JSON File*`</li></ul>  |
+| **GCR**  | <ul><li>`Username`</li></ul> <ul><li>`Service Account JSON File*`</li></ul>  |
+| **Quay**  | <ul><li>`Username`</li></ul> <ul><li>`Token`</li></ul>  |
+| **Other**  | <ul><li>`Username`</li></ul> <ul><li>`Password/Token`</li></ul>  |
 
-Here you can select the type of the Registry. We are supporting three types- `docker hub`, `ecr` and `others`. You can select any one of them from the drop-down. By default, this value is `ecr`. If you select ecr then you have to provide some information like- `AWS region, Access Key`, and `Secret Key`. If you select docker hub then you have to provide `Username` and `Password`. And if you select others then you have to provide the `Username` and `Password`.
+
+![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/container-registries/add-container-registry.jpg)
 
-### Registry URL
 
-Select any type of Registry from the drop-down, you have to provide the URL of your registry. Create your registry and provide the URL of that registry in the URL box.
+Please read each `registry type` in detail for you to help in choosing the right container registry for your application development needs.
+
+* [Registry Type: ECR](#registry-type-ecr)
+* [Registry Type: Docker](#registry-type-docker)
+* [Registry Type: Google Container Registry (GCR)](#registry-type-google-container-registry-gcr)
+* [Registry Type: Artifact Registry (GCP)](#registry-type-artifact-registry-gcp)
+* [Registry Type: Others](#registry-type-others)
+
 
 ### Registry Type: ECR
 
@@ -53,71 +62,152 @@ Before you begin, create an [IAM user](https://docs.aws.amazon.com/AmazonECR/lat
 | **Name** | User-defined name for the registry in Devtron |
 | **Registry Type** | Select **ECR** |
 | **Registry URL** | This is the URL of your private registry in AWS. <br></br> For example, the URL format is: `https://xxxxxxxxxxxx.dkr.ecr.<region>.amazonaws.com`. <br></br>`xxxxxxxxxxxx` is your 12-digit AWS account Id. |
-| **Authentication Type** | <br></br> * **EC2 IAM role**: Authenticate with workernode IAM role. <br></br> * **User Auth**: Authenticate with an authorization token <br></br>  - **Access key ID**: Your AWS access key <br></br>  - **Secret access key**: Your AWS secret access key ID |
+| **Authentication Type** | <br></br> * **EC2 IAM role**: Authenticate with workernode IAM role. <br></br> * **User Auth**: Authenticate with an authorization token <br></br>  - **Access key ID**: Your AWS access key. <br></br>  - **Secret access key**: Your AWS secret access key ID. |
 
 ![ECR Role-based authentication](https://devtron-public-asset.s3.us-east-2.amazonaws.com/Container-registeries/ECR-IAM-auth-role-based.png)
 
 ![ECR Key-based authentication](https://devtron-public-asset.s3.us-east-2.amazonaws.com/Container-registeries/ECR_user-auth-key-based.png)
 
-To set this `ECR` as the default registry hub for your images, select **[x] Set as default registry**.
+To set the `ECR` as the default registry hub for your images, enable the field **[x] Set as default registry** and then click **Save**.
 
-Select **Save**.
+To use the ECR container image, go to the **Applications** page and select your application, and then select **App Configuration > [Build Configuration](./../creating-application/docker-build-configuration.md)**.
 
-To use the ECR container image, go to the **Applications** page and select your application, and then select **App Configuration > [Docker Build Config](./../creating-application/docker-build-configuration.md)**.
+### Registry Type: Docker 
 
-### Registry Type- Docker Hub 
-
-You have to provide the below information if you select the registry type as Docker Hub.
+You have to provide below information if you select the registry type as `Docker`.
 
 * **Username**
 
-Give the username of the docker hub account you used for creating your registry in.
+Provide the username of the docker hub account you used for creating your registry.
 
 * **Password**
 
-Give the password/[token](https://docs.docker.com/docker-hub/access-tokens/) corresponding to your docker hub account.
+Provide the password/[Token](https://docs.docker.com/docker-hub/access-tokens/) corresponding to your docker hub account. 
+It is recommended to use `Token` for security purpose.
 
 ![](../../user-guide/global-configurations/images/Container_Registry_DockerHub.jpg)
 
-### Registry Type Others:
+### Registry Type: Google Container Registry (GCR) 
+
+You have to provide below information if you select the registry type as `GCR`.
+JSON key file authentication method can be used to authenticate with username and service account JSON file. Please follow [link](https://cloud.google.com/container-registry/docs/advanced-authentication#json-key) for getting username and service account JSON file for this registry. Please remove all the white spaces from json key and wrap it in single quote while putting in the `Service Account JSON File` field.  
+
+![](../../user-guide/global-configurations/images/Container_Registry_gcr.jpg)
 
-You have to provide the below information if you select the registry type as others.
+### Registry Type: Artifact Registry (GCP) 
 
-* **Username**
+You have to provide below information if you select the registry type as `Artifact Registry (GCP)`.
+JSON key file authentication method can be used to authenticate with username and service account JSON file. Please follow [link](https://cloud.google.com/artifact-registry/docs/docker/authentication#json-key) for getting username and service account JSON file for this registry. Please remove all the white spaces from json key and wrap it in single quote while putting in `Service Account JSON File` field.
 
-Give the username of your account, where you have created your registry in.
 
-* **Password**
+### Registry Type: Azure
+Service principal authentication method can be used to authenticate with username and password. Please follow [link](https://docs.microsoft.com/en-us/azure/container-registry/container-registry-auth-service-principal) for getting username and password for this registry.
 
-Give the password corresponding to the username of your registry.
 
-![](../../user-guide/global-configurations/images/Container_Registry_others.jpg)
+### Registry Type: Others
 
-### Set as default:
+You have to provide below information if you select the registry type as `Others`.
 
-If you enable the `Set as default` option, then this registry name will be set as default in the `Container Registry` section inside the `Docker build config` page. This is optional. You can keep it disabled.
+* **Username**
 
-### Advance Registry Url connection options:
+Provide the username of your account, where you have created your registry in.
 
-* If you enable the `Allow Only Secure Connection` option, then this registry allows only secure connections.
+* **Password/Token**
 
-* If you enable the `Allow Secure Connection With CA Certificate` option, then you have to upload/provide private CA certificate (ca.crt).
+Provide the Password/Token corresponding to the username of your registry.
 
-* If the container registry is insecure (for eg : SSL certificate is expired), then you enable the `Allow Insecure Connection` option.
+### Set as default registry:
 
-Now click on `Save` to save the configuration of the `Container registry`.
+If you enable the `Set as default registry` option, then the registry name will be set as default in the `Container Registry` section on the App Configuration >`Build Configuration` page. This field is optional. You can keep it disabled.
 
-### Note:
+### Advance Registry URL Connection Options:
 
+* If you enable the `Allow Only Secure Connection` option, then this registry allows only secure connections.
+* If you enable the `Allow Secure Connection With CA Certificate` option, then you have to upload/provide private CA certificate (ca.crt).
+* If the container registry is insecure (for eg : SSL certificate is expired), then you enable the `Allow Insecure Connection` option.
+
+#### Note:
 You can use any registry which can be authenticated using `docker login -u <username> -p <password> <registry-url>`. However these registries might provide a more secured way for authentication, which we will support later.
-Some popular registries which can be used using username and password mechanism:
 
-* **Google Container Registry (GCR)** : JSON key file authentication method can be used to authenticate with username and password. Please follow [link](https://cloud.google.com/container-registry/docs/advanced-authentication#json-key) for getting username and password for this registry. Please remove all the white spaces from json key and wrap it in single quote while putting in password field.  
 
-![](../../user-guide/global-configurations/images/Container_Registry_gcr.jpg)
+## Pull an Image from a Private Registry
+
+You can create a Pod that uses a `Secret` to pull an image from a private container image registry or repository. There are many private registries in use. This task uses [Docker Hub](https://www.docker.com/products/docker-hub) as an example registry.
+
+Super admin users can decide if they want to auto-inject registry credentials or use a secret to pull an image for deployment to environments on specific clusters.
+
+To manage the access of registry credentials, click **Manage**.
+
+There are two options to manage the access of registry credentials:
+
+| Fields | Description |
+| --- | --- |
+| **Do not inject credentials to clusters** | Select the clusters for which you do not want to inject credentials. |
+| **Auto-inject credentials to clusters** | Select the clusters for which you want to inject credentials. |
+
+You can choose one of the two options for defining credentials:
+
+* [User Registry Credentials](https://docs.devtron.ai/v/v0.6/getting-started/global-configurations/docker-registries#user-registry-credentials)
+* [Specify Image Pull Secret](https://docs.devtron.ai/v/v0.6/getting-started/global-configurations/docker-registries#specify-image-pull-secret) 
+
+### Use Registry Credentials
+
+If you select **Use Registry Credentials**, the clusters will be auto-injected with the registry credentials of your registry type. As an example: If you select `Docker` as Registry Type and `docker.io` as Registry URL, the registry credentials of the clusters will be the `username` and `password` which you define.
+Click **Save**.
+
+![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/container-registries/use-registry-credentials.jpg)
+
+
+### Specify Image Pull Secret
+
+You can create a Secret by providing credentials on the command line.
+
+![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/container-registries/specify-image-pull-secret-latest.png)
+
+Create this Secret, naming it `regcred`:
+
+```bash
+kubectl create -n <namespace> secret docker-registry regcred --docker-server=<your-registry-server> --docker-username=<your-name> --docker-password=<your-pword> --docker-email=<your-email>
+```
+
+where:
+* <namespace> is your virtual cluster. E.g., devtron-demo
+* <your-registry-server> is your Private Docker Registry FQDN. Use https://index.docker.io/v1/ for DockerHub.
+* <your-name> is your Docker username.
+* <your-pword> is your Docker password.
+* <your-email> is your Docker email.
+
+You have successfully set your Docker credentials in the cluster as a Secret called `regcred`.
+
+**Note**: Typing secrets on the command line may store them in your shell history unprotected, and those secrets might also be visible to other users on your PC during the time when kubectl is running.
+
+Enter the `Secret` name in the field and click **Save**.
+
+
+## How to resolve if Deployment Status shows Failed or Degraded
+
+If the deployment status shows `Failed` or `Degraded`, then the cluster is not able to pull container image from the private registry. In that case, the status of pod shows `ImagePullBackOff`.
+
+The failure of deployment can be one of the following reasons:
+
+* Provided credentials may not have permission to pull container image from registry.
+* Provided credentials may be invalid.
+
+You can resolve the `ImagePullBackOff` issue by clicking **How to resolve?** which will take you to the **App Details** page.
+
+![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/container-registries/how-to-resolve-latest1.png)
+
+
+To provide the auto-inject credentials to the specific clusters for pulling the image from the private repository, click **Manage Access** which will take you to the **Container Registries** page. 
+
+![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/container-registries/manage-access-latest.jpg)
+
+1. On the **Container Registries** page, select the docker registry and click **Manage**.
+2. In the **Auto-inject credentials to clusters**, click **Confirm to edit** to select the specific cluster or all clusters for which you want to auto-inject the credentials to and click **Save**.
+3. Redeploy the application after allowing the access.
+
+![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/container-registries/auto-inject-to-clusters.jpg)
 
-* **Google Artifact Registry (GAR)** : JSON key file authentication method can be used to authenticate with username and password. Please follow [link](https://cloud.google.com/artifact-registry/docs/docker/authentication#json-key) for getting username and password for this registry. Please remove all the white spaces from json key and wrap it in single quote while putting in password field.
-* **Azure Container Registry (ACR)** : Service principal authentication method can be used to authenticate with username and password. Please follow [link](https://docs.microsoft.com/en-us/azure/container-registry/container-registry-auth-service-principal) for getting username and password for this registry.
 
 ## Integrating With External Container Registry
 
@@ -135,3 +225,17 @@ secrets:
 ```     
 
 The `name` that you provide in values.yaml ie. `regcred` is name of the secret that will be used as `imagePullSecrets` to pull the image from docker hub to deploy. To know how `imagePullSecrets` will be used in the deployment-template, please follow the [documentation](https://docs.devtron.ai/devtron/user-guide/creating-application/deployment-template/rollout-deployment#imagepullsecrets).
+
+
+
+
+
+
+
+
+
+
+
+
+
+