1. Documentation
    2. history bug_report picture_as_pdf
×

Using manual mode with Amazon Web Services Secure Token Service

About manual mode with AWS Secure Token Service

In manual mode with STS, the individual OpenShift Container Platform cluster components use AWS Secure Token Service (STS) to assign components IAM roles that provide short-term, limited-privilege security credentials. These credentials are associated with IAM roles that are specific to each component that makes AWS API calls.

Requests for new and refreshed credentials are automated by using an appropriately configured AWS IAM OpenID Connect (OIDC) identity provider, combined with AWS IAM roles. OpenShift Container Platform signs service account tokens that are trusted by AWS IAM, and can be projected into a pod and used for authentication. Tokens are refreshed after one hour.

Detailed authentication flow between AWS and the cluster when using AWS STS
Figure 1. STS authentication flow

Using manual mode with STS changes the content of the AWS credentials that are provided to individual OpenShift Container Platform components.

AWS secret format using long-lived credentials
apiVersion: v1
kind: Secret
metadata:
  namespace: <target-namespace> (1)
  name: <target-secret-name> (2)
data:
  aws_access_key_id: <base64-encoded-access-key-id>
  aws_secret_access_key: <base64-encoded-secret-access-key>
1 The namespace for the component.
2 The name of the component secret.
AWS secret format with STS
apiVersion: v1
kind: Secret
metadata:
  namespace: <target-namespace> (1)
  name: <target-secret-name> (2)
stringData:
  credentials: |-
    [default]
    sts_regional_endpoints = regional
    role_name: <operator-role-name> (3)
    web_identity_token_file: <path-to-token> (4)
1 The namespace for the component.
2 The name of the component secret.
3 The IAM role for the component.
4 The path to the service account token inside the pod. By convention, this is /var/run/secrets/openshift/serviceaccount/token for OpenShift Container Platform components.

Installing an OpenShift Container Platform cluster configured for manual mode with STS

To install a cluster that is configured to use the Cloud Credential Operator (CCO) in manual mode with STS:

  1. Configure the Cloud Credential Operator utility.

  2. Create the required AWS resources individually, or with a single command.

  3. Run the OpenShift Container Platform installer.

  4. Verify that the cluster is using short-lived credentials.

Because the cluster is operating in manual mode when using STS, it is not able to create new credentials for components with the permissions that they require. When upgrading to a different minor version of OpenShift Container Platform, there are often new AWS permission requirements. Before upgrading a cluster that is using STS, the cluster administrator must manually ensure that the AWS permissions are sufficient for existing components and available to any new components.

Configuring the Cloud Credential Operator utility

To create and manage cloud credentials from outside of the cluster when the Cloud Credential Operator (CCO) is operating in manual mode with STS, extract and prepare the CCO utility (ccoctl) binary.

The ccoctl is a Linux binary that must run in a Linux environment.
Prerequisites

  • You have created an AWS account for the ccoctl to use with the following permissions:

    Table 1. Required AWS permissions
    iam permissions s3 permissions

    • iam:CreateOpenIDConnectProvider

    • iam:CreateRole

    • iam:DeleteOpenIDConnectProvider

    • iam:DeleteRole

    • iam:DeleteRolePolicy

    • iam:GetOpenIDConnectProvider

    • iam:GetRole

    • iam:GetUser

    • iam:ListOpenIDConnectProviders

    • iam:ListRolePolicies

    • iam:ListRoles

    • iam:PutRolePolicy

    • iam:TagOpenIDConnectProvider

    • iam:TagRole

    • s3:CreateBucket

    • s3:DeleteBucket

    • s3:DeleteObject

    • s3:GetBucketAcl

    • s3:GetBucketTagging

    • s3:GetObject

    • s3:GetObjectAcl

    • s3:GetObjectTagging

    • s3:ListBucket

    • s3:PutBucketAcl

    • s3:PutBucketTagging

    • s3:PutObject

    • s3:PutObjectAcl

    • s3:PutObjectTagging
Procedure

  1. Obtain the OpenShift Container Platform release image by running the following command:

    $ RELEASE_IMAGE=$(./openshift-install version | awk '/release image/ {print $3}')

  2. Obtain the CCO container image from the OpenShift Container Platform release image by running the following command:

    $ CCO_IMAGE=$(oc adm release info --image-for='cloud-credential-operator' $RELEASE_IMAGE -a ~/.pull-secret)

    Ensure that the architecture of the $RELEASE_IMAGE matches the architecture of the environment in which you will use the ccoctl tool.

  3. Extract the ccoctl binary from the CCO container image within the OpenShift Container Platform release image by running the following command:

    $ oc image extract $CCO_IMAGE --file="/usr/bin/ccoctl" -a ~/.pull-secret

  4. Change the permissions to make ccoctl executable by running the following command:

    $ chmod 775 ccoctl
Verification

  • To verify that ccoctl is ready to use, display the help file by running the following command:

    $ ccoctl --help
    Output of ccoctl --help:
    OpenShift credentials provisioning tool

Usage:
  ccoctl [command]

Available Commands:
  alibabacloud Manage credentials objects for alibaba cloud
  aws          Manage credentials objects for AWS cloud
  gcp          Manage credentials objects for Google cloud
  help         Help about any command
  ibmcloud     Manage credentials objects for IBM Cloud
  nutanix      Manage credentials objects for Nutanix

Flags:
  -h, --help   help for ccoctl

Use "ccoctl [command] --help" for more information about a command.

Creating AWS resources with the Cloud Credential Operator utility

You can use the CCO utility (ccoctl) to create the required AWS resources individually, or with a single command.