OSDOCS-10228

Author: jneczypor

_topic_maps/_topic_map_rosa.yml

@@ -30,6 +30,8 @@ Topics:
   File: index
 - Name: Learn more about ROSA with HCP
   File: about-hcp
+- Name: AWS STS and ROSA with HCP explained
+  File: cloud-experts-rosa-hcp-sts-explained
 - Name: Legal notice
   File: legal-notice
   Distros: openshift-rosa

cloud_experts_tutorials/cloud-experts-getting-started/cloud-experts-rosa-sts-explained.adoc

@@ -13,7 +13,7 @@ This tutorial outlines the two options for allowing {product-title} (ROSA) to in
 
 [NOTE]
 ====
-This content currently covers ROSA Classic with AWS STS and not does yet account for ROSA with hosted control planes (HCP) with AWS STS.
+This content currently covers ROSA Classic with AWS STS. For ROSA with hosted control planes (HCP) with AWS STS, see xref:../../welcome/cloud-experts-rosa-hcp-sts-explained.adoc#cloud-experts-rosa-hcp-sts-explained[AWS STS and ROSA with HCP explained].
 ====
 
 This tutorial will:

images/cloud-experts-sts-explained_creation_flow_hcp.png

@@ -0,0 +1,122 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="cloud-experts-rosa-hcp-sts-explained"]
+= AWS STS and ROSA with HCP explained
+include::_attributes/common-attributes.adoc[]
+include::_attributes/attributes-openshift-dedicated.adoc[]
+:context: cloud-experts-rosa-hcp-sts-explained
+
+toc::[]
+
+//rosaworkshop.io content metadata
+//Brought into ROSA product docs 2023-10-26
+//Modified for HCP 2024-4-16
+
+{hcp-title-first} uses an AWS (Amazon Web Services) Security Token Service (STS) for AWS Identity Access Management (IAM) to obtain the necessary credentials to interact with resources in your AWS account.
+
+[id="credential-methods-rosa-hcp"]
+== AWS STS credential method
+As part of {hcp-title}, Red Hat must be granted the necessary permissions to manage infrastructure resources in your AWS account.
+{hcp-title} grants the cluster's automation software limited, short-term access to resources in your AWS account. 
+
+The STS method uses predefined roles and policies to grant temporary, least-privilege permissions to IAM roles. The credentials typically expire an hour after being requested. Once expired, they are no longer recognized by AWS and no longer have account access from API requests made with them. For more information, see the link:https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html[AWS documentation].
+
+AWS IAM STS roles must be created for each {hcp-title} cluster. The ROSA command line interface (CLI) (`rosa`) manages the STS roles and helps you attach the ROSA-specific, AWS-managed policies to each role. The CLI provides the commands and files to create the roles, attach the AWS-managed policies, and an option to allow the CLI to automatically create the roles and attach the policies. 
+//See [insert new xref when we have one for HCP] for more information about the different `--mode` options.
+
+[id="hcp-sts-security"]
+== AWS STS security
+Security features for AWS STS include:
+
+* An explicit and limited set of policies that the user creates ahead of time.
+** The user can review every requested permission needed by the platform.
+* The service cannot do anything outside of those permissions.
+* There is no need to rotate or revoke credentials. Whenever the service needs to perform an action, it obtains credentials that expire in one hour or less.
+* Credential expiration reduces the risks of credentials leaking and being reused.
+
+{hcp-title} grants cluster software components least-privilege permissions with short-term security credentials to specific and segregated IAM roles. The credentials are associated with IAM roles specific to each component and cluster that makes AWS API calls. This method aligns with principles of least-privilege and secure practices in cloud service resource management.
+
+[id="components-specific-to-rosa-hcp-with-sts"]
+== Components of {hcp-title}
+* *AWS infrastructure* - The infrastructure required for the cluster including the Amazon EC2 instances, Amazon EBS storage, and networking components. See xref:../rosa_architecture/rosa_policy_service_definition/rosa-service-definition.adoc#rosa-sdpolicy-aws-compute-types_rosa-service-definition[AWS compute types] to see the supported instance types for compute nodes and xref:../rosa_planning/rosa-sts-aws-prereqs.adoc#rosa-ec2-instances_rosa-sts-aws-prereqs[provisioned AWS infrastructure] for more information on cloud resource configuration.
+* *AWS STS* - A method for granting short-term, dynamic tokens to provide users the necessary permissions to temporarily interact with your AWS account resources.
+* *OpenID Connect (OIDC)* - A mechanism for cluster Operators to authenticate with AWS, assume the cluster roles through a trust policy, and obtain temporary credentials from AWS IAM STS to make the required API calls.
+* *Roles and policies* - The roles and policies used by {hcp-title} can be divided into account-wide roles and policies and Operator roles and policies.
++
+The policies determine the allowed actions for each of the roles. See xref:../rosa_architecture/rosa-sts-about-iam-resources.adoc#rosa-sts-about-iam-resources[About IAM resources for ROSA clusters that use STS] for more details about the individual roles and policies and xref:../rosa_planning/rosa-sts-ocm-role.adoc#rosa-sts-ocm-role[ROSA IAM role resource] for more details about trust policies.
++
+--
+** The account-wide roles are:
++
+*** ManagedOpenShift-Installer-Role
+*** ManagedOpenShift-Worker-Role
+*** ManagedOpenShift-Support-Role
++
+** The account-wide AWS-managed policies are:
++
+*** link:https://docs.aws.amazon.com/aws-managed-policy/latest/reference/ROSAInstallerPolicy.html[ROSAInstallerPolicy]
+*** link:https://docs.aws.amazon.com/aws-managed-policy/latest/reference/ROSAWorkerInstancePolicy.html[ROSAWorkerInstancePolicy]
+*** link:https://docs.aws.amazon.com/aws-managed-policy/latest/reference/ROSASRESupportPolicy.html[ROSASRESupportPolicy]
+*** link:https://docs.aws.amazon.com/aws-managed-policy/latest/reference/ROSAIngressOperatorPolicy.html[ROSAIngressOperatorPolicy]
+*** link:https://docs.aws.amazon.com/aws-managed-policy/latest/reference/ROSAAmazonEBSCSIDriverOperatorPolicy.html[ROSAAmazonEBSCSIDriverOperatorPolicy]
+*** link:https://docs.aws.amazon.com/aws-managed-policy/latest/reference/ROSACloudNetworkConfigOperatorPolicy.html[ROSACloudNetworkConfigOperatorPolicy]
+*** link:https://docs.aws.amazon.com/aws-managed-policy/latest/reference/ROSAControlPlaneOperatorPolicy.html[ROSAControlPlaneOperatorPolicy]
+*** link:https://docs.aws.amazon.com/aws-managed-policy/latest/reference/ROSAImageRegistryOperatorPolicy.html[ROSAImageRegistryOperatorPolicy]
+*** link:https://docs.aws.amazon.com/aws-managed-policy/latest/reference/ROSAKMSProviderPolicy.html[ROSAKMSProviderPolicy]
+*** link:https://docs.aws.amazon.com/aws-managed-policy/latest/reference/ROSAKubeControllerPolicy.html[ROSAKubeControllerPolicy]
+*** link:https://docs.aws.amazon.com/aws-managed-policy/latest/reference/ROSAManageSubscription.html[ROSAManageSubscription]
+*** link:https://docs.aws.amazon.com/aws-managed-policy/latest/reference/ROSANodePoolManagementPolicy.html[ROSANodePoolManagementPolicy]
+--
++
+[NOTE]
+====
+Certain policies are used by the cluster Operator roles, listed below. The Operator roles are created in a second step because they are dependent on an existing cluster name and cannot be created at the same time as the account-wide roles.
+====
++
+** The Operator roles are:
++
+*** <operator_role_prefix>-openshift-cluster-csi-drivers-ebs-cloud-credentials
+*** <operator_role_prefix>-openshift-cloud-network-config-controller-cloud-credentials
+*** <operator_role_prefix>-openshift-machine-api-aws-cloud-credentials
+*** <operator_role_prefix>-openshift-cloud-credential-operator-cloud-credentials
+*** <operator_role_prefix>-openshift-image-registry-installer-cloud-credentials
+*** <operator_role_prefix>-openshift-ingress-operator-cloud-credentials
++
+** Trust policies are created for each account-wide role and each Operator role.
+
+[id="deploying-rosa-hcp-with-sts-cluster"]
+== Deploying a {hcp-title} cluster
+
+Deploying a {hcp-title} cluster follows the following steps:
+
+. You create the account-wide roles.
+. You create the Operator roles.
+. Red Hat uses AWS STS to send the required permissions to AWS that allow AWS to create and attach the corresponding AWS-manged Operator policies.
+. You create the OIDC provider.
+. You create the cluster.
+
+During the cluster creation process, the ROSA CLI creates the required JSON files for you and outputs the commands you need. If desired, the ROSA CLI can also run the commands for you.
+
+The ROSA CLI can automatically create the roles for you, or you can manually create them by using the `--mode manual` or `--mode auto` flags. For further details about deployment, see xref:../rosa_install_access_delete_clusters/rosa-sts-creating-a-cluster-with-customizations.adoc#rosa-sts-creating-cluster-customizations_rosa-sts-creating-a-cluster-with-customizations[Creating a cluster with customizations].
+//Change the above xref when we have HCP specific docs
+
+[id="hcp-sts-process"]
+== {hcp-title} workflow
+The user creates the required account-wide roles. During role creation, a trust policy, known as a cross-account trust policy, is created which allows a Red Hat-owned role to assume the roles. Trust policies are also created for the EC2 service, which allows workloads on EC2 instances to assume roles and obtain credentials. AWS assigns a corresponding permissions policy to each role.
+
+After the account-wide roles and policies are created, the user can create a cluster. Once cluster creation is initiated, the user creates the Operator roles so that cluster Operators can make AWS API calls. These roles are then assigned to the corresponding permission policies that were created earlier and a trust policy with an OIDC provider. The Operator roles differ from the account-wide roles in that they ultimately represent the pods that need access to AWS resources. Because a user cannot attach IAM roles to pods, they must create a trust policy with an OIDC provider so that the Operator, and therefore the pods, can access the roles they need.
+
+Once the user assigns the roles to the corresponding policy permissions, the final step is creating the OIDC provider.
+
+image::cloud-experts-sts-explained_creation_flow_hcp.png[]
+
+When a new role is needed, the workload currently using the Red Hat role will assume the role in the AWS account, obtain temporary credentials from AWS STS, and begin performing the actions using API calls within the user's AWS account as permitted by the assumed role's permissions policy. The credentials are temporary and have a maximum duration of one hour.
+
+image::cloud-experts-sts-explained_highlevel.png[]
+
+//The entire workflow is depicted in the following graphic:
+
+//image::cloud-experts-sts-explained_entire_flow_hcp.png[]
+
+Operators use the following process to obtain the requisite credentials to perform their tasks. Each Operator is assigned an Operator role, a permissions policy, and a trust policy with an OIDC provider. The Operator will assume the role by passing a JSON web token that contains the role and a token file (`web_identity_token_file`) to the OIDC provider, which then authenticates the signed key with a public key. The public key is created during cluster creation and stored in an S3 bucket. The Operator then confirms that the subject in the signed token file matches the role in the role trust policy which ensures that the OIDC provider can only obtain the allowed role. The OIDC provider then returns the temporary credentials to the Operator so that the Operator can make AWS API calls. For a visual representation, see the following diagram:
+
+image::cloud-experts-sts-explained_oidc_op_roles_hcp.png[]