Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart 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
Copy link

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
Copy link

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
Copy link

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

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.

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
Copy link

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.

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
    Copy to Clipboard Toggle word wrap
  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>
    Copy to Clipboard Toggle word wrap

  4. Restart Central to apply the changes. 

    $ kubectl -n stackrox delete pod -l app=central
    Copy to Clipboard Toggle word wrap

  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 
    
        }
    ]
}
    Copy to Clipboard Toggle word wrap
    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"
    }
  ]
}
    Copy to Clipboard Toggle word wrap
    1
    The <role-name> should match with the new role you have created earlier.

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 
      
        }
    ]
}
      Copy to Clipboard Toggle word wrap
      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"
    }
  ]
}
    Copy to Clipboard Toggle word wrap
1.3.2.1.3. Configuring AssumeRole in RHACS
Copy link

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.

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

Prerequisites

  • You have a workload identity or service account key for authentication.

    For more information, see Authenticate to Google Cloud APIs from GKE workloads (Google Cloud documentation).

  • You have access to the registry for the associated service account.

    For more information, see Access control with IAM (Google Cloud documentation).

  • You have granted the following roles to the service account, if you use GCR Container Analysis:

Procedure

  1. In the RHACS portal, click Platform Configuration Integrations.
  2. In the Image Integrations section, click Google Container Registry.
  3. To create a new integration, click New integration.
  4. Enter a name for your integration.

  5. Choose the appropriate type of integration that you want to configure:

    • To configure an integration that includes the container image registry, select Registry.
    • To configure an integration that includes Scanner, select Scanner.
    • To configure an integration that includes the container image registry and Scanner, select Registry+Scanner.
  6. Enter the address of your registry.
  7. Optional: Enter the name of your Google Cloud project. RHACS matches the images against the project of the registry. If you do not specify the project name, RHACS matches the images against all the projects.
  8. Optional: Select the Use workload identity checkbox to authenticate by using a workload identity.
  9. Enter your service account key for authentication.
  10. Optional: Select the Create integration without testing checkbox to create your integration without testing the connection to the registry.
  11. Optional: To test your integration with the selected registry, click Test.
  12. To save your integration, click Save.

You can integrate Red Hat Advanced Cluster Security for Kubernetes (RHACS) with the Google Artifact Registry (GAR).

Prerequisites

  • You have a workload identity or service account key for authentication.

    For more information, see Authenticate to Google Cloud APIs from GKE workloads (Google Cloud documentation).

  • You have the artifact registry reader Identity and Access Management (IAM) role, roles/artifactregistry.reader for the associated service account.

Procedure

  1. In the RHACS portal, click Platform Configuration Integrations.
  2. In the Image Integrations section, click Google Artifact Registry.
  3. To create a new integration, click New integration.
  4. Enter a name for your integration.
  5. Enter the address of your registry.
  6. Optional: Enter the name of your Google Cloud project. RHACS matches the images against the project of the registry. If you do not specify the project name, RHACS matches the images against all the projects.
  7. Optional: Select the Use workload identity checkbox to authenticate by using a workload identity.
  8. Enter your service account key for authentication.
  9. Optional: Select the Create integration without testing checkbox to create your integration without testing the connection to the registry.
  10. Optional: To test your integration with the selected registry, click Test.
  11. To save your integration, click Save.

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

Prerequisites

  • You have either an Azure managed or Azure workload identity.

    For more information about Azure managed identities, see What are managed identities for Azure resources? (Microsoft Azure documentation).

    For more information about Azure workload identities, see Workload identity federation (Microsoft Azure documentation).

  • You have the Reader role for the identity over a scope that includes the container registry.

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.
    4. Optional: Select the Use workload identity checkbox, if you want to authenticate by using an Azure managed or workload identity.
  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
Copy link

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.

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 Red Hat Quay Robot Account overview topic in Quay documentation for more information.
    • By using keyless authentication with external secret: This method uses OIDC federation and the External Secrets Operator (ESO). For more information, see "Enabling Quay registry keyless authentication using external secret".
  • 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. For more information, 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.

For validating images stored in Quay private registries, you can configure RHACS to use keyless authentication with Red Hat Quay registries. This method uses the External Secrets Operator (ESO) and OpenID Connect (OIDC) federation.

Prerequisites

  • You have enabled delegated scanning in RHACS. For more information, see "Accessing delegated image scanning" in the "Additional resources" section.
  • The Central endpoint configured for the Secured Cluster centralEndpoint: central.stackrox:443 or similar.

  • A robot account created in Red Hat Quay with OIDC federation configured.

    • The issuer URL in the Quay robot identity federation configuration must match the service account token issuer of your OpenShift Container Platform cluster.
    • The sub claim subject must match the service account name and namespace that you configure in your cluster.

    See the Red Hat Quay Robot Account overview topic in Quay documentation for more information.

Procedure

  1. In your Quay instance, navigate to your robot account settings and configure OIDC federation.

    Ensure the Issuer URL and Subject fields are correctly set to match your OpenShift Container Platform service account that ESO uses. See the Setting up robot account federation topic in the Red Hat Quay documentation for more information.

  2. If ESO is not already present in your cluster, install it using Helm or another preferred method. 

    $ helm repo add external-secrets https://charts.external-secrets.io
helm install external-secrets \
  external-secrets/external-secrets \
  -n external-secrets \
  --create-namespace
    Copy to Clipboard Toggle word wrap

  3. Define and apply the following Kubernetes resources. This example creates a ServiceAccount resource, a QuayAccessToken generator resource provided by the ESO installation, and an ExternalSecret resource that uses the generator to create a kubernetes.io/dockerconfigjson secret in the specified namespace.

    Important

    Update the robotAccount field in the QuayAccessToken resource to match the name of your Quay robot account. 

    apiVersion: v1
kind: ServiceAccount
metadata:
  name: quay
  namespace: quay
---
apiVersion: generators.external-secrets.io/v1alpha1
kind: QuayAccessToken
metadata:
  name: quay-token
  namespace: quay
spec:
  url: quay.io
  robotAccount: keyless+account
    1 
    
  serviceAccountRef:
    name: quay
    namespace: quay
---
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: quay-credentials
  namespace: quay
spec:
  dataFrom:
  - sourceRef:
      generatorRef:
        apiVersion: generators.external-secrets.io/v1alpha1
        kind: QuayAccessToken
        name: quay-token
  refreshInterval: 55m
  target:
    name: quay-credentials
    template:
      type: kubernetes.io/dockerconfigjson
      data:
        .dockerconfigjson: |
          {
            "auths": {
              "{{ .registry }}": {
                "auth": "{{ .auth }}"
              }
            }
          }
    Copy to Clipboard Toggle word wrap
    1
    Replace keyless+account with the actual name of your Quay robot account.

Verification

  • Confirm that ESO has successfully created a secret named quay-credentials of type kubernetes.io/dockerconfigjson in the specified namespace. 

    $ kubectl get secret quay-credentials -n quay -o yaml
    Copy to Clipboard Toggle word wrap

The keyless authentication method supports image scanning by using delegated scanning.

  • Use delegated image scanning by running the following command: 

    $ roxctl image scan <image_name> --namespace=<namespace_where_secret_exists>
    1
    Copy to Clipboard Toggle word wrap
    1
    Specify the image name and namespace where you created the secret.

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

Prerequisites

Procedure

  1. In the RHACS portal, go to Platform Configuration Integrations.
  2. In the Image Integrations section, select GitHub 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: The GitHub username. Leave blank for anonymous access.
    4. GitHub Token: The GitHub personal access token. Leave blank for anonymous access.
  5. Select Create integration without testing to create the integration without testing the connection to the registry. Enable this option to allow anonymous access.
  6. Select Test to test that the integration with the selected registry is working.
  7. Select Save.

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.

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.
Back to top
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. Explore our recent updates.

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.

Theme

© 2025 Red Hat