SupportConsoleDevelopersStart a trialContact

Chapter 1. Integrating with image registries

Red Hat Advanced Cluster Security for Kubernetes (RHACS) integrates with a variety of image registries so that you can understand your images and apply security policies for image usage.

When you integrate with image registries, you can view important image details, such as image creation date and Dockerfile details (including image layers).

After you integrate RHACS with your registry, you can scan images, view image components, and apply security policies to images before or after deployment.

Note

When you integrate with an image registry, RHACS does not scan all images in your registry. RHACS only scans the images when you:

  • Use the images in deployments
  • Use the roxctl CLI to check images
  • Use a continuous integration (CI) system to enforce security policies

You can integrate RHACS with major image registries, including:

1.1. Automatic configuration

Red Hat Advanced Cluster Security for Kubernetes includes default integrations with standard registries, such as Docker Hub and others. It can also automatically configure integrations based on artifacts found in the monitored clusters, such as image pull secrets. Usually, you do not need to configure registry integrations manually.

Important
  • If you use a Google Container Registry (GCR), Red Hat Advanced Cluster Security for Kubernetes does not create a registry integration automatically.
  • If you use Red Hat Advanced Cluster Security Cloud Service, automatic configuration is unavailable, and you must manually create registry integrations.

1.2. Amazon ECR integrations

For Amazon ECR integrations, Red Hat Advanced Cluster Security for Kubernetes automatically generates ECR registry integrations if the following conditions are met:

  • The cloud provider for the cluster is AWS.
  • The nodes in your cluster have an Instance Identity and Access Management (IAM) Role association and the Instance Metadata Service is available in the nodes. For example, when using Amazon Elastic Kubernetes Service (EKS) to manage your cluster, this role is known as the EKS Node IAM role.
  • The Instance IAM role has IAM policies granting access to the ECR registries from which you are deploying.

If the listed conditions are met, Red Hat Advanced Cluster Security for Kubernetes monitors deployments that pull from ECR registries and automatically generates ECR integrations for them. You can edit these integrations after they are automatically generated.

1.3. Manually configuring image registries

If you are using GCR, you must manually create image registry integrations.

1.3.1. Manually configuring OpenShift Container Platform registry

You can integrate Red Hat Advanced Cluster Security for Kubernetes with OpenShift Container Platform built-in container image registry.

Prerequisites

  • You need a username and a password for authentication with the OpenShift Container Platform registry.

Procedure

  1. In the RHACS portal, go to Platform Configuration Integrations.
  2. Under the Image Integrations section, select Generic Docker Registry.
  3. Click New integration.

  4. Enter the details for the following fields:

    1. Integration name: The name of the integration.
    2. Endpoint: The address of the registry.
    3. Username and Password.
  5. If you are not using a TLS certificate when connecting to the registry, select Disable TLS certificate validation (insecure).
  6. Select Create integration without testing to create the integration without testing the connection to the registry.
  7. Select Test to test that the integration with the selected registry is working.
  8. Select Save.

1.3.2. Manually configuring Amazon Elastic Container Registry

You can use Red Hat Advanced Cluster Security for Kubernetes to create and modify Amazon Elastic Container Registry (ECR) integrations manually. If you are deploying from Amazon ECR, integrations for the Amazon ECR registries are usually automatically generated. However, you might want to create integrations on your own to scan images outside deployments. You can also modify the parameters of an automatically-generated integration. For example, you can change the authentication method used by an automatically-generated Amazon ECR integration to use AssumeRole authentication or other authorization models.

Important

To erase changes you made to an automatically-generated ECR integration, delete the integration, and Red Hat Advanced Cluster Security for Kubernetes creates a new integration for you with the automatically-generated parameters when you deploy images from Amazon ECR.

Prerequisites

  • You must have an Amazon Identity and Access Management (IAM) access key ID and a secret access key. Alternatively, you can use a node-level IAM proxy such as kiam or kube2iam.
  • The access key must have read access to ECR. See How do I create an AWS access key? for more information.

  • If you are running Red Hat Advanced Cluster Security for Kubernetes in Amazon Elastic Kubernetes Service (EKS) and want to integrate with an ECR from a separate Amazon account, you must first set a repository policy statement in your ECR. Follow the instructions at Setting a repository policy statement and for Actions, choose the following scopes of the Amazon ECR API operations:

    • ecr:BatchCheckLayerAvailability
    • ecr:BatchGetImage
    • ecr:DescribeImages
    • ecr:GetDownloadUrlForLayer
    • ecr:ListImages

Procedure

  1. In the RHACS portal, go to Platform Configuration Integrations.
  2. Under the Image Integrations section, select Amazon ECR.
  3. Click New integration, or click one of the automatically-generated integrations to open it, then click Edit.

  4. Enter or modify the details for the following fields:

    1. Update stored credentials: Clear this box if you are modifying an integration without updating the credentials such as access keys and passwords.
    2. Integration name: The name of the integration.
    3. Registry ID: The ID of the registry.
    4. Endpoint: The address of the registry. This value is required only if you are using a private virtual private cloud (VPC) endpoint for Amazon ECR. This field is not enabled when the AssumeRole option is selected.
    5. Region: The region for the registry; for example, us-west-1.
  5. If you are using IAM, select Use Container IAM role. Otherwise, clear the Use Container IAM role box and enter the Access key ID and Secret access key.

  6. If you are using AssumeRole authentication, select Use AssumeRole and enter the details for the following fields:

    1. AssumeRole ID: The ID of the role to assume.
    2. AssumeRole External ID (optional): If you are using an external ID with AssumeRole, you can enter it here.
  7. Select Create integration without testing to create the integration without testing the connection to the registry.
  8. Select Test to test that the integration with the selected registry is working.
  9. Select Save.

1.3.2.1. Using assumerole with Amazon ECR

You can use AssumeRole to grant access to AWS resources without manually configuring each user’s permissions. Instead, you can define a role with the desired permissions so that the user is granted access to assume that role. AssumeRole enables you to grant, revoke, or otherwise generally manage more fine-grained permissions.

1.3.2.1.1. Configuring AssumeRole with container IAM

Before you can use AssumeRole with Red Hat Advanced Cluster Security for Kubernetes, you must first configure it.

Procedure

  1. Enable the IAM OIDC provider for your EKS cluster: 

    $ eksctl utils associate-iam-oidc-provider --cluster <cluster name> --approve
  2. Create an IAM role for your EKS cluster.

  3. Associate the newly created role with a service account: 

    $ kubectl -n stackrox annotate sa central eks.amazonaws.com/role-arn=arn:aws:iam::67890:role/<role-name>

  4. Restart Central to apply the changes. 

    $ kubectl -n stackrox delete pod -l app=central

  5. Assign the role to a policy that allows the role to assume another role as required: 

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "sts:AssumeRole",
            "Resource": "arn:aws:iam::<ecr-registry>:role/<assumerole-readonly>" 1
        }
    ]
}
    1
    Replace <assumerole-readonly> with the role you want to assume.

  6. Update the trust relationship for the role you want to assume: 

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "arn:aws:iam::<ecr-registry>:role/<role-name>" 1
        ]
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
    1
    The <role-name> should match with the new role you have created earlier.
1.3.2.1.2. Configuring AssumeRole without container IAM

To use AssumeRole without container IAM, you must use an access and a secret key to authenticate as an AWS user with programmatic access.

Procedure

  1. Depending on whether the AssumeRole user is in the same account as the ECR registry or in a different account, you must either:

    • Create a new role with the desired permissions if the user for which you want to assume role is in the same account as the ECR registry.

      Note

      When creating the role, you can choose any trusted entity as required. However, you must modify it after creation.

    • Or, you must provide permissions to access the ECR registry and define its trust relationship if the user is in a different account than the ECR registry: 

      {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "sts:AssumeRole",
            "Resource": "arn:aws:iam::<ecr-registry>:role/<assumerole-readonly>" 1
        }
    ]
}
      1
      Replace <assumerole-readonly> with the role you want to assume.

  2. Configure the trust relationship of the role by including the user ARN under the Principal field: 

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "arn:aws:iam::<ecr-registry>:user/<role-name>"
        ]
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
1.3.2.1.3. Configuring AssumeRole in RHACS

After configuring AssumeRole in ECR, you can integrate Red Hat Advanced Cluster Security for Kubernetes with Amazon Elastic Container Registry (ECR) by using AssumeRole.

Procedure

  1. In the RHACS portal, go to Platform Configuration Integrations.
  2. Under the Image Integrations section, select Amazon ECR.
  3. Click New Integration.

  4. Enter the details for the following fields:

    1. Integration Name: The name of the integration.
    2. Registry ID: The ID of the registry.
    3. Region: The region for the registry; for example, us-west-1.
  5. If you are using IAM, select Use container IAM role. Otherwise, clear the Use custom IAM role box and enter the Access key ID and Secret access key.

  6. If you are using AssumeRole, select Use AssumeRole and enter the details for the following fields:

    1. AssumeRole ID: The ID of the role to assume.
    2. AssumeRole External ID (optional): If you are using an external ID with AssumeRole, you can enter it here.
  7. Select Test to test that the integration with the selected registry is working.
  8. Select Save.

1.3.3. Manually configuring Google Container Registry

You can integrate Red Hat Advanced Cluster Security for Kubernetes with Google Container Registry (GCR).

Prerequisites

  • You need either a workload identity or a service account key for authentication.
  • The associated service account must have access to the registry. See Configuring access control for information about granting users and other projects access to GCR.

  • If you are using GCR Container Analysis, you must also grant the following roles to the service account:

    • Container Analysis Notes Viewer
    • Container Analysis Occurrences Viewer
    • Storage Object Viewer

Procedure

  1. In the RHACS portal, go to Platform Configuration Integrations.
  2. Under the Image Integrations section, select Google Container Registry.
  3. Click New integration.

  4. Enter the details for the following fields:

    1. Integration name: The name of the integration.
    2. Type: Select Registry.
    3. Registry Endpoint: The address of the registry.
    4. Project: The Google Cloud project name.
    5. Use workload identity: Check to authenticate using a workload identity.
    6. Service account key (JSON): Your service account key for authentication.
  5. Select Create integration without testing to create the integration without testing the connection to the registry.
  6. Select Test to test that the integration with the selected registry is working.
  7. Select Save.

1.3.4. Manually configuring Google Artifact Registry

You can integrate Red Hat Advanced Cluster Security for Kubernetes with Google Artifact Registry.

Prerequisites

  • You need either a workload identity or a service account key for authentication.
  • The associated service account must have the Artifact Registry Reader Identity and Access Management (IAM) role roles/artifactregistry.reader.

Procedure

  1. In the RHACS portal, go to Platform Configuration Integrations.
  2. Under the Image Integrations section, select Google Artifact Registry.
  3. Click New integration.

  4. Enter the details for the following fields:

    1. Integration name: The name of the integration.
    2. Registry endpoint: The address of the registry.
    3. Project: The Google Cloud project name.
    4. Use workload identity: Check to authenticate using a workload identity.
    5. Service account key (JSON): Your service account key for authentication.
  5. Select Create integration without testing to create the integration without testing the connection to the registry.
  6. Select Test to test that the integration with the selected registry is working.
  7. Select Save.

1.3.5. Manually configuring Microsoft Azure Container Registry

You can integrate Red Hat Advanced Cluster Security for Kubernetes with Microsoft Azure Container Registry.

Prerequisites

  • You must have a username and a password for authentication.

Procedure

  1. In the RHACS portal, go to Platform Configuration Integrations.
  2. Under the Image Integrations section, select Microsoft Azure Container Registry.
  3. Click New integration.

  4. Enter the details for the following fields:

    1. Integration name: The name of the integration.
    2. Endpoint: The address of the registry.
    3. Username and Password.
  5. Select Create integration without testing to create the integration without testing the connection to the registry.
  6. Select Test to test that the integration with the selected registry is working.
  7. Select Save.

1.3.6. Manually configuring JFrog Artifactory

You can integrate Red Hat Advanced Cluster Security for Kubernetes with JFrog Artifactory.

Prerequisites

  • You must have a username and a password for authentication with JFrog Artifactory.

Procedure

  1. In the RHACS portal, go to Platform Configuration Integrations.
  2. Under the Image Integrations section, select JFrog Artifactory.
  3. Click New integration.

  4. Enter the details for the following fields:

    1. Integration name: The name of the integration.
    2. Endpoint: The address of the registry.
    3. Username and Password.
  5. If you are not using a TLS certificate when connecting to the registry, select Disable TLS certificate validation (insecure).
  6. Select Create integration without testing to create the integration without testing the connection to the registry.
  7. Select Test to test that the integration with the selected registry is working.
  8. Select Save.

1.3.7. Manually configuring Quay Container Registry

You can integrate Red Hat Advanced Cluster Security for Kubernetes (RHACS) with Quay Container Registry. You can integrate with Quay by using the following methods:

  • Integrating with the Quay public repository (registry): This method does not require authentication.
  • Integrating with a Quay private registry by using a robot account: This method requires that you create a robot account to use with Quay (recommended). See the Quay documentation for more information.
  • Integrating with Quay to use the Quay scanner rather than the RHACS scanner: This method uses the API and requires an OAuth token for authentication. See "Integrating with Quay Container Registry to scan images" in the "Additional Resources" section.

Prerequisites

  • For authentication with a Quay private registry, you need the credentials associated with a robot account or an OAuth token (deprecated).

Procedure

  1. In the RHACS portal, go to Platform Configuration Integrations.
  2. Under the Image Integrations section, select Red Hat Quay.io.
  3. Click New integration.
  4. Enter the Integration name.

  5. Enter the Endpoint, or the address of the registry.

    1. If you are integrating with the Quay public repository, under Type, select Registry, and then go to the next step.

    2. If you are integrating with a Quay private registry, under Type, select Registry and enter information in the following fields:

      • Robot username: If you are accessing the registry by using a Quay robot account, enter the user name in the format <namespace>+<accountname>.
      • Robot password: If you are accessing the registry by using a Quay robot account, enter the password for the robot account user name.
      • OAuth token: If you are accessing the registry by using an OAuth token (deprecated), enter it in this field.
  6. Optional: If you are not using a TLS certificate when connecting to the registry, select Disable TLS certificate validation (insecure).
  7. Optional: To create the integration without testing, select Create integration without testing.
  8. Select Save.
Note

If you are editing a Quay integration but do not want to update your credentials, verify that Update stored credentials is not selected.

1.4. Additional resources

1.4.1. Manually configuring IBM Cloud Container Registry

You can integrate Red Hat Advanced Cluster Security for Kubernetes with IBM Cloud Container Registry.

Prerequisites

  • You must have an API key for authentication with the IBM Cloud Container Registry.

Procedure

  1. In the RHACS portal, go to Platform Configuration Integrations.
  2. Under the Image Integrations section, select IBM Cloud Container Registry.
  3. Click New integration.

  4. Enter the details for the following fields:

    1. Integration name: The name of the integration.
    2. Endpoint: The address of the registry.
    3. API key.
  5. Select Test to test that the integration with the selected registry is working.
  6. Select Save.

1.4.2. Manually configuring Red Hat Container Registry

You can integrate Red Hat Advanced Cluster Security for Kubernetes with Red Hat Container Registry.

Prerequisites

  • You must have a username and a password for authentication with the Red Hat Container Registry.

Procedure

  1. In the RHACS portal, go to Platform Configuration Integrations.
  2. Under the Image Integrations section, select Red Hat Registry.
  3. Click New integration.

  4. Enter the details for the following fields:

    1. Integration name: The name of the integration.
    2. Endpoint: The address of the registry.
    3. Username and Password.
  5. Select Create integration without testing to create the integration without testing the connection to the registry.
  6. Select Test to test that the integration with the selected registry is working.
  7. Select Save.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.