# Private registry with AWS Secrets Manager sample for CodeBuild
Private registry with AWS Secrets Manager sample

 This sample shows you how to use a Docker image that is stored in a private registry as your AWS CodeBuild runtime environment. The credentials for the private registry are stored in AWS Secrets Manager. Any private registry works with CodeBuild. This sample uses Docker Hub. 

**Note**  
Secrets are visible to actions and are not masked when written to a file.

**Topics**
+ [

## Private registry sample requirements
](#sample-private-registry-requirements)
+ [

# Create a CodeBuild project with a private registry
](private-registry-sample-create-project.md)
+ [

# Configure a private registry credential for self-hosted runners
](private-registry-sample-configure-runners.md)

## Private registry sample requirements


 To use a private registry with AWS CodeBuild, you must have the following: 
+  A Secrets Manager secret that stores your Docker Hub credentials. The credentials are used to access your private repository. 
**Note**  
You will be charged for secrets that you create.
+  A private repository or account. 
+  A CodeBuild service role IAM policy that grants access to your Secrets Manager secret. 

 Follow these steps to create these resources and then create a CodeBuild build project using the Docker images stored in your private registry. 

# Create a CodeBuild project with a private registry


1. For information about how to create a free private repository, see [Repositories on Docker Hub](https://docs.docker.com/docker-hub/repos/). You can also run the following commands in a terminal to pull an image, get its ID, and push it to a new repository. 

   ```
   docker pull amazonlinux
   docker images amazonlinux --format {{.ID}}
   docker tag image-id your-username/repository-name:tag
   docker login
   docker push your-username/repository-name
   ```

1.  Follow the steps in [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html) in the *AWS Secrets Manager User Guide*.

   

   1.  In step 3, in **Choose secret type**, choose **Other type of secret**. 

   1. In **Key/value pairs**, create one key-value pair for your Docker Hub user name and one key-value pair for your Docker Hub password. 

   1.  Continue following the steps in [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html). 

   1.  In step 5, on the **Configure automatic rotation** page, turn it off because the keys correspond to your Docker Hub credentials. 

   1.  Finish following the steps in [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html). 

    For more information, see [What is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) 

1.  When you create an AWS CodeBuild project in the console, CodeBuild attaches the required permission for you. If you use an AWS KMS key other than `DefaultEncryptionKey`, you must add it to the service role. For more information, see [Modifying a role (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_manage_modify.html#roles-managingrole-editing-console) in the *IAM User Guide*. 

    For your service role to work with Secrets Manager, it must have, at a minimum, the `secretsmanager:GetSecretValue` permission.   
![\[The service role configuration.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/private-registry-sample-iam.png)

1.  To use the console to create a project with an environment stored in a private registry, do the following while you create a project. For information, see [Create a build project (console)](create-project.md#create-project-console). 
**Note**  
 If your private registry is in your VPC, it must have public internet access. CodeBuild cannot pull an image from a private IP address in a VPC. 

   1.  In **Environment image**, choose **Custom image**. 

   1.  For **Environment type**, choose **Linux** or **Windows**. 

   1.  For **Image registry**, choose **Other registry**. 

   1.  In **External registry URL**, enter the image location and in **Registry credential - optional** enter the ARN or name of your Secrets Manager credentials.
**Note**  
 If your credentials do not exist in your current Region, then you must use the ARN. You cannot use the credential name if the credentials exist in a different Region. 

# Configure a private registry credential for self-hosted runners
New content: Configure a private registry credential for self-hosted runners

Add support for setting registry credentials when using custom images from non-private registries. 

Use the following instructions to configure a registry credential for a self-hosted runner.

**Note**  
Note that these credentials will only be used if the images are overridden with those from private registries. 

------
#### [ AWS Management Console ]

1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home).

1. Create a build project or select an existing project. For information, see [Create a build project (console)](create-project.md#create-project-console) and [Change a build project's settings (console)](change-project.md#change-project-console).

1.  In **Environment**, choose **Additional configuration**. 

1.  In **Additional configuration**, enter the name or ARN of the secret from AWS Secrets Manager for **Registry credential - optional**.  
![\[The registry credential configuration.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/registry-credential.png)

------
#### [ AWS CLI ]

1. If you'd like to create a new project, run the **create-project** command.

   ```
   aws codebuild create-project \
       --name project-name \
       --source type=source-type,location=source-location \
       --environment "type=environment-type,image=image,computeType=compute-type,registryCredential={credentialProvider=SECRETS_MANAGER,credential=secret-name-or-arn},imagePullCredentialsType=CODEBUILD|SERVICE_ROLE" \
       --artifacts type=artifacts-type \
       --service-role arn:aws:iam::account-ID:role/service-role/service-role-name
   ```

1. If you'd like to update an existing project, run the **update-project** command.

   ```
   aws codebuild update-project \
       --name project-name \
       --environment "type=environment-type,image=image,computeType=compute-type,registryCredential={credentialProvider=SECRETS_MANAGER,credential=secret-name-or-arn}"
   ```

------