From 0577aae7ca8b2eb9c1fa40be0c786638d1ef0f11 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 7 Aug 2023 17:32:50 +0200 Subject: [PATCH] scout: add docs on ecr integration Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- content/scout/integrations/_index.md | 2 +- content/scout/integrations/registry/ecr.md | 210 +++++++++++++++++++++ data/redirects.yml | 2 + data/toc.yaml | 2 + 4 files changed, 215 insertions(+), 1 deletion(-) create mode 100644 content/scout/integrations/registry/ecr.md diff --git a/content/scout/integrations/_index.md b/content/scout/integrations/_index.md index 719ca9fca6..aa7d4e4a3c 100644 --- a/content/scout/integrations/_index.md +++ b/content/scout/integrations/_index.md @@ -26,7 +26,7 @@ aren't hosted on Docker Hub. The following container registry integrations are available: - [Artifactory](./registry/artifactory.md) -- Amazon ECR (coming soon) +- [Amazon Elastic Container Registry](./registry/ecr.md) ### Continuous Integration diff --git a/content/scout/integrations/registry/ecr.md b/content/scout/integrations/registry/ecr.md new file mode 100644 index 0000000000..d108fa3176 --- /dev/null +++ b/content/scout/integrations/registry/ecr.md @@ -0,0 +1,210 @@ +--- +description: Integrate Amazon Elastic Container Registry with Docker Scout +keywords: docker scout, ecr, integration, image analysis, security, cves +title: Integrate Docker Scout with Amazon ECR +--- + +{% include scout-early-access.md %} + +Integrating Docker Scout with Amazon Elastic Container Registry (ECR) lets you +view image insights for images hosted in ECR repositories. After integrating +Docker Scout with ECR and activating Docker Scout for a repository, pushing an +image to the repository automatically triggers image analysis. You can view +image insights using the Docker Scout Dashboard, or the `docker scout` CLI +commands. + +## How it works + +To help you integrate Docker Scout with ECR, you can use a CloudFormation stack +template that creates and configures the necessary AWS resources for +integrating Docker Scout with your ECR registry. For more details about the AWS +resources, see [CloudFormation stack template](#cloudformation-stack-template) + +The following diagram shows how the Docker Scout ECR integration works. + +```mermaid +sequenceDiagram + autonumber + box User + participant User + end + box User's AWS + participant EventBridge + participant SNSTopic + participant SecretsManager + participant ECR + end + box Docker Scout + participant Scout API + end + + # During setup + SNSTopic ->> Scout: CloudFormation Stack Event + Scout ->> SecretsManager: Set up Scout credentials for EventBridge + + # After integration + User ->> ECR: Push an image + EventBridge -->> Scout: Push image Event + Scout ->> ECR: Login, and pull image + ECR ->> Scout: Pull image +``` + +After the integration, Docker Scout automatically pulls and analyzes images +that you push to the ECR registry. Metadata about your images are stored on the +Docker Scout platform, but Docker Scout doesn't store the container images +themselves. For more information about how Docker Scout handles image data, see +[Data handling](../../data-handling.md). + +### CloudFormation stack template + +The following table describes the configuration resources. + +> **Note** +> +> Creating these resources incurs a small, recurring cost on the AWS account. +> The **Cost** column in the table represents an estimated monthly cost of the +> resources, when integrating an ECR registry that gets 100 images pushed per day. + +| Resource type | Resource name | Description | Cost | +| ----------------------------- | ---------------------- | -------------------------------------------------------------------------------------------- | ----- | +| `AWS::SNSTopic::Topic` | `SNSTopic` | SNS topic for notifying Docker Scout when the AWS resources have been created. | Free | +| `AWS::SNS::TopicPolicy` | `TopicPolicy` | Defines the topic for the initial setup notification. | Free | +| `AWS::SecretsManager::Secret` | `ScoutAPICredentials` | Stores the credentials used by EventBridge to fire events to Scout. | $0.42 | +| `AWS::Events::ApiDestination` | `ApiDestination` | Sets up the EventBridge connection to Docker Scout for sending ECR push and delete events. | $0.01 | +| `AWS::Events::Connection` | `Connection` | EventBridge connection credentials to Scout. | Free | +| `AWS::Events::Rule` | `Rule` | Defines the rule to send ECR pushes and deletes to Scout. | Free | +| `AWS::IAM::Role` | `InvokeApiRole` | Internal role to grant the event access to `ApiDestination`. | Free | +| `AWS::IAM::Role` | `AssumeRoleEcrAccess` | This role has access to `ScoutAPICredentials` for setting up the Docker Scout integration. | Free | + +## Integrate your first registry + +Create the CloudFormation stack in your AWS account to enable the Docker Scout +integration. + +Prerequisites: + +- You must have access to an AWS account with permission to create resources. +- You have be an owner of the Docker organization + +To create the stack: + +1. Go to [ECR integrations](https://scout.docker.com/settings/integrations/ecr) + on the Docker Scout Dashboard. +2. Make sure the correct Docker organization is selected in the Dashboard + header. + + If not, switch organizations using the drop-down menu. + +3. Select the **Create on AWS** button. +{ #create-on-aws } + + This opens the **Create stack** wizard in the AWS CloudFormation console in + a new browser tab. If you're not already signed in to AWS, you're redirected + to the sign-in page first. + + If the button is grayed-out, it means you're lacking the necessary + permissions in the Docker organization. + +4. Follow the steps in the **Create stack** wizard until the end, and complete + the procedure by creating the resources. + + The fields in the wizard are pre-populated by the CloudFormation template, + so you don't need to edit any of the fields. + +5. When the resources have been created (the CloudFormation status shows + `CREATE_COMPLETE` in the AWS console), return to the + [ECR integrations](https://scout.docker.com/settings/integrations/ecr) page + in the Docker Scout Dashboard. + + The **Integrated registries** list shows the account ID and region for the + ECR registry that you just integrated. If successful, the integration status + is **Connected**. + +The ECR integration is now active. For Docker Scout to start analyzing images +in the registry, you need to activate it for each repository. Refer to +[repository settings](../../dashboard.md#repository-settings). + +After activating repositories, images that you push will be analyzed by Docker +Scout, and the analysis results will appear in the Docker Scout Dashboard. + +## Integrate additional registries + +To add additional registries, + +1. Go to [ECR integrations](https://scout.docker.com/settings/integrations/ecr) + on the Docker Scout Dashboard. +2. Make sure the correct Docker organization is selected in the Dashboard + header. + + If not, switch organizations using the drop-down menu. + +3. Select the **Add** button at the top of the list. +4. Complete the steps for [creating the AWS resources](#create-on-aws) + +Next, activate Docker Scout for the repositories that you want to analyze in +[repository settings](../../dashboard.md#repository-settings). + +## Remove integration + +To remove an integrated ECR registry, you must be an owner of the Docker +organization. + +1. Go to [ECR integrations](https://scout.docker.com/settings/integrations/ecr) + on the Docker Scout Dashboard. +2. Find the registry that you want to remove in the list of integrated + registries, and select the remove icon in the **Actions** column. + + If the remove icon is disabled, it means that you're lacking the necessary + permissions in the Docker organization. + +3. In the dialog that opens, confirm by selecting **Remove**. + +> **Important** +> +> Removing the integration from the Docker Scout dashboard doesn't remove the +> AWS resources in your account. +> +> After removing the integration in Docker Scout, go to the AWS console and +> delete the **ScoutECRIntegration** CloudFormation stack for the integraiton +> that you want to remove. +{ .important } + +## Troubleshooting + +### Unable to integrate registry + +Check the **Status** of the integration on the +[ECR integrations](https://scout.docker.com/settings/integrations/ecr) page. + +- If the status is **Pending** for a prolonged period of time, it's an + indication that the integration was not yet completed on the AWS side. Select + the **Pending** link to open the CloudFormation wizard, and complete all the + steps. + +- An **Error** status indicates that something's gone wrong in the back-end. + You can try [removing the integration](#remove-integration) and recreating it + again. + +### ECR images not showing in the dashboard + +If image analysis results for your ECR images aren't showing up in the Docker +Scout Dashboard, run the following checks: + +- Ensure that you've activated Docker Scout for the repository. View and manage + active repositories in [repository settings](../../dashboard.md#repository-settings). + +- Ensure that the AWS account ID and region for your registry is listed on the + [ECR integrations](https://scout.docker.com/settings/integrations/ecr) page. + + The account ID and region are included in the registry hostname: + `.dkr.ecr..amazonaws.com/` + +- Docker Scout only analyzes images that were pushed *after* the integration + was created. If you want to analyze images created before the registry was + integrated, you can push the images to the registry again. + + ```console + $ docker login .dkr.ecr..amazonaws.com/ + $ docker pull .dkr.ecr..amazonaws.com/ + $ docker push .dkr.ecr..amazonaws.com/ + ``` diff --git a/data/redirects.yml b/data/redirects.yml index 5a3d5499b2..bd35869d6a 100644 --- a/data/redirects.yml +++ b/data/redirects.yml @@ -591,6 +591,8 @@ - "/go/scout-jenkins/" "/scout/integrations/registry/artifactory": - /go/scout-artifactory/ +"/scout/integrations/registry/ecr/": + - "/go/scout-ecr/" # Telepresence "/develop/remote-development/": diff --git a/data/toc.yaml b/data/toc.yaml index 7de8a00890..9fafdfcf54 100644 --- a/data/toc.yaml +++ b/data/toc.yaml @@ -1923,6 +1923,8 @@ Manuals: section: - title: Artifactory path: /scout/integrations/registry/artifactory/ + - title: Elastic Container Registry + path: /scout/integrations/registry/ecr/ - sectiontitle: Continuous integration section: - title: GitHub Actions