:_mod-docs-content-type: ASSEMBLY
[id="cco-mode-sts"]
= Using manual mode with Amazon Web Services Security Token Service
include::_attributes/common-attributes.adoc[]
:context: cco-mode-sts

toc::[]

Manual mode with STS is supported for Amazon Web Services (AWS).

[NOTE]
====
This credentials strategy is supported for only new {product-title} clusters and must be configured during installation. You cannot reconfigure an existing cluster that uses a different credentials strategy to use this feature.
====

[id="sts-mode-about_{context}"]
== About manual mode with AWS Security Token Service

In manual mode with STS, the individual {product-title} cluster components use AWS Security 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. {product-title} 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.

.STS authentication flow
image::347_OpenShift_credentials_with_STS_updates_0623_AWS.png[Detailed authentication flow between AWS and the cluster when using AWS STS]

Using manual mode with STS changes the content of the AWS credentials that are provided to individual {product-title} components.

.AWS secret format using long-lived credentials

[source,yaml]
----
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

[source,yaml]
----
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 {product-title} components.

//Supertask: Installing an OCP cluster configured for manual mode with STS
[id="sts-mode-installing_{context}"]
== Installing an {product-title} 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:

//[pre-4.8]. xref:../../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#sts-mode-installing-manual-config_cco-mode-sts[Create the required AWS resources]
. xref:../../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#cco-ccoctl-configuring_cco-mode-sts[Configure the Cloud Credential Operator utility].
. Create the required AWS resources xref:../../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#cco-ccoctl-creating-individually_cco-mode-sts[individually], or xref:../../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#cco-ccoctl-creating-at-once_cco-mode-sts[with a single command].
. xref:../../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#sts-mode-installing-manual-run-installer_cco-mode-sts[Run the {product-title} installer].
. xref:../../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#sts-mode-installing-verifying_cco-mode-sts[Verify that the cluster is using short-lived credentials].

[NOTE]
====
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 {product-title}, 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.
====

[role="_additional-resources"]
.Additional resources

* xref:../../updating/preparing_for_updates/preparing-manual-creds-update.adoc#cco-ccoctl-configuring_preparing-manual-creds-update[Configuring the Cloud Credential Operator utility for a cluster update]

//[pre-4.8]Task part 1: Creating AWS resources manually
//include::modules/sts-mode-installing-manual-config.adoc[leveloffset=+2]

//Task part 1: Configuring the Cloud Credential Operator utility
include::modules/cco-ccoctl-configuring.adoc[leveloffset=+2]

[id="sts-mode-create-aws-resources-ccoctl_{context}"]
=== Creating AWS resources with the Cloud Credential Operator utility

You can use the CCO utility (`ccoctl`) to create the required AWS resources xref:../../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#cco-ccoctl-creating-individually_cco-mode-sts[individually], or xref:../../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#cco-ccoctl-creating-at-once_cco-mode-sts[with a single command].

//Task part 2a: Creating the required AWS resources individually
include::modules/cco-ccoctl-creating-individually.adoc[leveloffset=+3]

//Task part 2b: Creating the required AWS resources all at once
include::modules/cco-ccoctl-creating-at-once.adoc[leveloffset=+3]

//Task part 3: Run the OCP installer
include::modules/sts-mode-installing-manual-run-installer.adoc[leveloffset=+2]

//Task part 4: Verify that the cluster is using short-lived credentials
include::modules/sts-mode-installing-verifying.adoc[leveloffset=+2]

[role="_additional-resources"]
[id="additional-resources_{context}"]
== Additional resources

* xref:../../updating/preparing_for_updates/preparing-manual-creds-update.adoc#preparing-manual-creds-update[Preparing to update a cluster with manually maintained credentials]
