Merge pull request #81465 from laubai/osdocs-11879-cluster-admin-details

OSDOCS#11879: Create cluster-admin during cluster deployment

Author: xenolinux

modules/rosa-classic-cluster-terraform-file-creation.adoc

@@ -1,7 +1,6 @@
 // Module included in the following assemblies:
 //
 // * rosa_install_access_delete_clusters/rosa-classic-creating-a-cluster-quickly-terraform.adoc
-//
 
 :_content-type: PROCEDURE
 
@@ -102,11 +101,25 @@ module "rosa-classic" {
   multi_az               = var.multi_az
   create_account_roles   = true
   create_operator_roles  = true
-
+# Optional: Configure a cluster administrator user <.>
+# 
+# Option 1: Default cluster-admin user
+# Create an administrator user (cluster-admin) and automatically
+# generate a password by uncommenting the following parameter:
+#  create_admin_user = true
+# Generated administrator credentials are displayed in terminal output.
+#
+# Option 2: Specify administrator username and password
+# Create an administrator user and define your own password
+# by uncommenting and editing the values of the following parameters:
+#  admin_credentials_username = <username>
+#  admin_credentials_password = <password>
+    
   depends_on = [time_sleep.wait_60_seconds]
 }
 EOF
 ----
+<.> Optional: Create an administrator user during cluster creation by uncommenting the appropriate parameters and editing their values.
 
 . Create the `variables.tf` file by running the following command:
 +

modules/rosa-create-objects.adoc

@@ -204,6 +204,15 @@ a|--cluster-name <cluster_name>
 |--controlplane-iam-role <arn>
 |The ARN of the IAM role to attach to control plane instances.
 
+|--create-cluster-admin
+|Optional. As part of cluster creation, create a local administrator user (`cluster-admin`) for your cluster. This automatically configures an htpasswd identity provider for the `cluster-admin` user. Optionally, use the `--cluster-admin-user` and `--cluster-admin-password` options to specify the username and password for the administrator user. Omitting these options automatically generates the credentials and displays their values as terminal output.
+
+|--cluster-admin-user
+|Optional. Specifies the user name of the cluster administrator user created when used in conjunction with the `--create-cluster-admin` option.
+
+|--cluster-admin-password
+|Optional. Specifies the password of the cluster administrator user created when used in conjunction with the `--create-cluster-admin` option.
+
 |--disable-scp-checks
 |Indicates whether cloud permission checks are disabled when attempting to install a cluster.
 

modules/rosa-hcp-cluster-terraform-file-creation.adoc

@@ -38,7 +38,7 @@ terraform {
       version = ">= 4.20.0"
     }
     rhcs = {
-      version = ">= 1.6.2"
+      version = ">= 1.6.3"
       source  = "terraform-redhat/rhcs"
     }
   }
@@ -85,7 +85,7 @@ resource "time_sleep" "wait_60_seconds" {
 
 module "rosa-hcp" {
   source                 = "terraform-redhat/rosa-hcp/rhcs"
-  version                = "1.6.2"
+  version                = "1.6.3"
   cluster_name           = local.cluster_name
   openshift_version      = var.openshift_version
   account_role_prefix    = local.cluster_name
@@ -97,11 +97,25 @@ module "rosa-hcp" {
   aws_subnet_ids         = var.create_vpc ? var.private_cluster ? module.vpc[0].private_subnets : concat(module.vpc[0].public_subnets, module.vpc[0].private_subnets) : var.aws_subnet_ids
   create_account_roles   = true
   create_operator_roles  = true
+# Optional: Configure a cluster administrator user <.>
+# 
+# Option 1: Default cluster-admin user
+# Create an administrator user (cluster-admin) and automatically
+# generate a password by uncommenting the following parameter:
+#  create_admin_user = true
+# Generated administrator credentials are displayed in terminal output.
+#
+# Option 2: Specify administrator username and password
+# Create an administrator user and define your own password
+# by uncommenting and editing the values of the following parameters:
+#  admin_credentials_username = <username>
+#  admin_credentials_password = <password>
     
   depends_on = [time_sleep.wait_60_seconds]
 }
 EOF
 ----
+<.> Optional: Create an administrator user during cluster creation by uncommenting the appropriate parameters and editing their values if required.
 
 . Create the `variables.tf` file by running the following command:
 +
@@ -265,4 +279,4 @@ module "vpc" {
 EOF
 ----
 +
-You are ready to initiate Terraform.
+You are ready to initiate Terraform.

modules/rosa-sts-creating-a-cluster-with-customizations-cli.adoc

@@ -51,8 +51,8 @@ $ rosa create account-roles --interactive \ <1>
 ----
 <1> `interactive` mode enables you to specify configuration options at the interactive prompts. For more information, see _Interactive cluster creation mode reference_.
 <2> `manual` mode generates the `aws` CLI commands and JSON files needed to create the account-wide roles and policies. After review, you must run the commands manually to create the resources.
-+
 --
++
 .Example output
 [source,terminal,subs="attributes+"]
 ----
@@ -222,51 +222,53 @@ Any optional fields can be left empty and a default will be selected.
 ? Domain prefix: <domain_prefix> <1>
 ? Deploy cluster with Hosted Control Plane (optional): No
 ? Create cluster admin user: Yes <2>
-? Username: user-admin <2>
-? Password: [? for help] *************** <2>
-? OpenShift version: 4.17.0 <3>
-? Configure the use of IMDSv2 for ec2 instances optional/required (optional): <4>
-I: Using arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-Installer-Role for the Installer role <5>
+? Create custom password for cluster admin: No <3>
+I: cluster admin user is cluster-admin
+I: cluster admin password is password
+? OpenShift version: <openshift_version> <4>
+? Configure the use of IMDSv2 for ec2 instances optional/required (optional): <5>
+I: Using arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-Installer-Role for the Installer role <6>
 I: Using arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-ControlPlane-Role for the ControlPlane role
 I: Using arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-Worker-Role for the Worker role
 I: Using arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-Support-Role for the Support role
-? External ID (optional): <6>
-? Operator roles prefix: <cluster_name>-<random_string> <7>
+? External ID (optional): <7>
+? Operator roles prefix: <cluster_name>-<random_string> <8>
 ? Deploy cluster using pre registered OIDC Configuration ID:
-? Tags (optional) <8>
-? Multiple availability zones (optional): No <9>
+? Tags (optional) <9>
+? Multiple availability zones (optional): No <10>
 ? AWS region: us-east-1
 ? PrivateLink cluster (optional): No
 ? Machine CIDR: 10.0.0.0/16
 ? Service CIDR: 172.30.0.0/16
 ? Pod CIDR: 10.128.0.0/14
-? Install into an existing VPC (optional): Yes <10>
+? Install into an existing VPC (optional): Yes <11>
 ? Subnet IDs (optional):
 ? Select availability zones (optional): No
-? Enable Customer Managed key (optional): No <11>
+? Enable Customer Managed key (optional): No <12>
 ? Compute nodes instance type (optional):
 ? Enable autoscaling (optional): No
 ? Compute nodes: 2
 ? Worker machine pool labels (optional):
 ? Host prefix: 23
-? Additional Security Group IDs (optional): <12>
+? Additional Security Group IDs (optional): <13>
 ? > [*]  sg-0e375ff0ec4a6cfa2 ('sg-1')
 ? > [ ]  sg-0e525ef0ec4b2ada7 ('sg-2')
-? Enable FIPS support: No <13>
-? Encrypt etcd data: No <14>
+? Enable FIPS support: No <14>
+? Encrypt etcd data: No <15>
 ? Disable Workload monitoring (optional): No
 I: Creating cluster '<cluster_name>'
 I: To create this cluster again in the future, you can run:
-   rosa create cluster --cluster-name <cluster_name> --role-arn arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-Installer-Role --support-role-arn arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-Support-Role --master-iam-role arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-ControlPlane-Role --worker-iam-role arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-Worker-Role --operator-roles-prefix <cluster_name>-<random_string> --region us-east-1 --version 4.17.0 --additional-compute-security-group-ids sg-0e375ff0ec4a6cfa2 --additional-infra-security-group-ids sg-0e375ff0ec4a6cfa2 --additional-control-plane-security-group-ids sg-0e375ff0ec4a6cfa2 --replicas 2 --machine-cidr 10.0.0.0/16 --service-cidr 172.30.0.0/16 --pod-cidr 10.128.0.0/14 --host-prefix 23 <15>
+   rosa create cluster --cluster-name <cluster_name> --role-arn arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-Installer-Role --support-role-arn arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-Support-Role --master-iam-role arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-ControlPlane-Role --worker-iam-role arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-Worker-Role --operator-roles-prefix <cluster_name>-<random_string> --region us-east-1 --version 4.17.0 --additional-compute-security-group-ids sg-0e375ff0ec4a6cfa2 --additional-infra-security-group-ids sg-0e375ff0ec4a6cfa2 --additional-control-plane-security-group-ids sg-0e375ff0ec4a6cfa2 --replicas 2 --machine-cidr 10.0.0.0/16 --service-cidr 172.30.0.0/16 --pod-cidr 10.128.0.0/14 --host-prefix 23 <16>
 I: To view a list of clusters and their status, run 'rosa list clusters'
 I: Cluster '<cluster_name>' has been created.
 I: Once the cluster is installed you will need to add an Identity Provider before you can login into the cluster. See 'rosa create idp --help' for more information.
 ...
 ----
 <1> Optional. When creating your cluster, you can customize the subdomain for your cluster on `*.openshiftapps.com` using the `--domain-prefix` flag. The value for this flag must be unique within your organization, cannot be longer than 15 characters, and cannot be changed after cluster creation. If the flag is not supplied, an autogenerated value is created that depends on the length of the cluster name. If the cluster name is fewer than or equal to 15 characters, that name is used for the domain prefix. If the cluster name is longer than 15 characters, the domain prefix is randomly generated to a 15 character string.
-<2> When creating your cluster, you can create a local administrator user for your cluster. Selecting `Yes` then prompts you to create a user name and password for the cluster admin. The user name must not contain `/`, `:`, or `%`. The password must be at least 14 characters (ASCII-standard) without whitespaces. This process automatically configures an htpasswd identity provider.
-<3> When creating the cluster, the listed `OpenShift version` options include the major, minor, and patch versions, for example `4.17.0`.
-<4> Optional: Specify 'optional' to configure all EC2 instances to use both v1 and v2 endpoints of EC2 Instance Metadata Service (IMDS). This is the default value. Specify 'required' to configure all EC2 instances to use IMDSv2 only.
+<2> When creating your cluster, you can create a local administrator user (`cluster-admin`) for your cluster. This automatically configures an `htpasswd` identity provider for the `cluster-admin` user.
+<3> You can create a custom password for the `cluster-admin` user, or have the system generate a password. If you do not create a custom password, the generated password is displayed in the command line output. If you specify a custom password, the password must be at least 14 characters (ASCII-standard) without any whitespace. When defined, the password is hashed and transported securely.
+<4> When creating the cluster, the listed `OpenShift version` options include the major, minor, and patch versions, for example `4.17.0`.
+<5> Optional: Specify `optional` to configure all EC2 instances to use both v1 and v2 endpoints of EC2 Instance Metadata Service (IMDS). This is the default value. Specify `required` to configure all EC2 instances to use IMDSv2 only.
 +
 ifdef::openshift-rosa[]
 [IMPORTANT]
@@ -275,15 +277,15 @@ The Instance Metadata Service settings cannot be changed after your cluster is c
 ====
 endif::openshift-rosa[]
 +
-<5> If you have more than one set of account roles for your cluster version in your AWS account, an interactive list of options is provided.
-<6> Optional: Specify an unique identifier that is passed by {product-title} and the OpenShift installer when an account role is assumed. This option is only required for custom account roles that expect an external ID.
-<7> By default, the cluster-specific Operator role names are prefixed with the cluster name and a random 4-digit hash. You can optionally specify a custom prefix to replace `<cluster_name>-<hash>` in the role names. The prefix is applied when you create the cluster-specific Operator IAM roles. For information about the prefix, see _Defining an Operator IAM role prefix_.
+<6> If you have more than one set of account roles for your cluster version in your {AWS} account, an interactive list of options is provided.
+<7> Optional: Specify an unique identifier that is passed by {product-title} and the OpenShift installer when an account role is assumed. This option is only required for custom account roles that expect an external ID.
+<8> By default, the cluster-specific Operator role names are prefixed with the cluster name and a random 4-digit hash. You can optionally specify a custom prefix to replace `<cluster_name>-<hash>` in the role names. The prefix is applied when you create the cluster-specific Operator IAM roles. For information about the prefix, see _About custom Operator IAM role prefixes_.
 +
 [NOTE]
 ====
 If you specified custom ARN paths when you created the associated account-wide roles, the custom path is automatically detected. The custom path is applied to the cluster-specific Operator roles when you create them in a later step.
 ====
-<8> Optional: Specify a tag that is used on all resources created by {product-title} in AWS. Tags can help you manage, identify, organize, search for, and filter resources within AWS. Tags are comma separated, for example: "key value, data input".
+<9> Optional: Specify a tag that is used on all resources created by {product-title} in AWS. Tags can help you manage, identify, organize, search for, and filter resources within AWS. Tags are comma separated, for example: `key value, data input`.
 +
 [IMPORTANT]
 ====
@@ -292,16 +294,16 @@ Tags that are added by Red{nbsp}Hat are required for clusters to stay in complia
 
 {product-title} does not support adding additional tags outside of ROSA cluster-managed resources. These tags can be lost when AWS resources are managed by the ROSA cluster. In these cases, you might need custom solutions or tools to reconcile the tags and keep them intact.
 ====
-<9> Optional: Multiple availability zones are recommended for production workloads. The default is a single availability zone.
-<10> Optional: You can create a cluster in an existing VPC, or ROSA can create a new VPC to use.
+<10> Optional: Multiple availability zones are recommended for production workloads. The default is a single availability zone.
+<11> Optional: You can create a cluster in an existing VPC, or ROSA can create a new VPC to use.
 +
 [WARNING]
 ====
 You cannot install a ROSA cluster into an existing VPC that was created by the OpenShift installer. These VPCs are created during the cluster deployment process and must only be associated with a single cluster to ensure that cluster provisioning and deletion operations work correctly.
 
 To verify whether a VPC was created by the OpenShift installer, check for the `owned` value on the `kubernetes.io/cluster/<infra-id>` tag. For example, when viewing the tags for the VPC named `mycluster-12abc-34def`, the `kubernetes.io/cluster/mycluster-12abc-34def` tag has a value of `owned`. Therefore, the VPC was created by the installer and must not be modified by the administrator.
 ====
-<11> Optional: Enable this option if you are using your own AWS KMS key to encrypt the control plane, infrastructure, worker node root volumes, and PVs. Specify the ARN for the KMS key that you added to the account-wide role ARN in the preceding step.
+<12> Optional: Enable this option if you are using your own AWS KMS key to encrypt the control plane, infrastructure, worker node root volumes, and PVs. Specify the ARN for the KMS key that you added to the account-wide role ARN in the preceding step.
 +
 [IMPORTANT]
 ====
@@ -310,16 +312,16 @@ Only persistent volumes (PVs) created from the default storage class are encrypt
 PVs created by using any other storage class are still encrypted, but the PVs are not encrypted with this key unless the storage class is specifically configured to use this key.
 ====
 
-<12> Optional: You can select additional custom security groups to use in your cluster. You must have already created the security groups and associated them with the VPC you selected for this cluster. You cannot add or edit security groups for the default machine pools after you create the machine pool. For more information, see the requirements for _Security groups_ under _Additional resources_.
-<13> Optional: Enable this option if you require your cluster to be FIPS validated. Selecting this option means the encrypt etcd data option is enabled by default and cannot be disabled. You can encrypt etcd data without enabling FIPS support.
-<14> Optional: Enable this option if your use case only requires etcd key value encryption in addition to the control plane storage encryption that encrypts the etcd volumes by default. With this option, the etcd key values are encrypted but not the keys.
+<13> Optional: You can select additional custom security groups to use in your cluster. You must have already created the security groups and associated them with the VPC you selected for this cluster. You cannot add or edit security groups for the default machine pools after you create the machine pool. For more information, see the requirements for _Security groups_ under _Additional resources_.
+<14> Optional: Enable this option if you require your cluster to be FIPS validated. Selecting this option means the encrypt etcd data option is enabled by default and cannot be disabled. You can encrypt etcd data without enabling FIPS support.
+<15> Optional: Enable this option if your use case only requires etcd key value encryption in addition to the control plane storage encryption that encrypts the etcd volumes by default. With this option, the etcd key values are encrypted but not the keys.
 +
 [IMPORTANT]
 ====
 By enabling etcd encryption for the key values in etcd, you will incur a performance overhead of approximately 20%. The overhead is a result of introducing this second layer of encryption, in addition to the default control plane storage encryption that encrypts the etcd volumes. Red{nbsp}Hat recommends that you enable etcd encryption only if you specifically require it for your use case.
 ====
 +
-<15> The output includes a custom command that you can run to create another cluster with the same configuration.
+<16> The output includes a custom command that you can run to create another cluster with the same configuration.
 --
 +
 As an alternative to using the `--interactive` mode, you can specify the customization options directly when you run the `rosa create cluster` command. Run the `rosa create cluster --help` command to view a list of available CLI options, or see _create cluster_ in _Managing objects with the ROSA CLI_.

modules/rosa-sts-interactive-cluster-creation-mode-options.adoc

@@ -26,7 +26,10 @@ The following table describes the interactive cluster creation mode options:
 |Enable the use of Hosted Control Planes.
 
 |`Create cluster admin user`
-|Create a cluster administrator user when you create your cluster using the htpasswd identity provider. The username must not contain `/`, `:`, or `%`. The password must be at least 14 characters (ASCII-standard) without whitespaces.
+a|Create a local administrator user (`cluster-admin`) for your cluster. This automatically configures a htpasswd identity provider for the `cluster-admin` user.
+
+|`Create custom password for cluster admin`
+a|Create a custom password for the `cluster-admin` user, or use a system-generated password. If you create a custom password, the password must be at least 14 characters (ASCII-standard) and contain no whitespace characters. If you do not create a custom password, the system generates a password and displays it in the command line output.
 
 |`Deploy cluster using AWS STS`
 |Create an OpenShift cluster that uses the AWS Security Token Service (STS) to allocate temporary, limited-privilege credentials for component-specific AWS Identity and Access Management (IAM) roles. The service enables cluster components to make AWS API calls using secure cloud resource management practices. The default is `Yes`.