Manually creating IAM for Azure Stack Hub - Installing on Azure Stack Hub | Installing

Alternatives to storing administrator-level secrets in the kube-system project
Manually create IAM
Upgrading clusters with manually maintained credentials
Next steps

In environments where the cloud identity and access management (IAM) APIs are not reachable, you must put the Cloud Credential Operator (CCO) into manual mode before you install the cluster.

Alternatives to storing administrator-level secrets in the kube-system project

The Cloud Credential Operator (CCO) manages cloud provider credentials as Kubernetes custom resource definitions (CRDs). You can configure the CCO to suit the security requirements of your organization by setting different values for the credentialsMode parameter in the install-config.yaml file.

Additional resources

For a detailed description of all available CCO credential modes and their supported platforms, see About the Cloud Credential Operator.

Manually create IAM

The Cloud Credential Operator (CCO) only supports your cloud provider in manual mode. As a result, you must specify the identity and access management (IAM) secrets for your cloud provider.

Procedure

Change to the directory that contains the installation program and create the install-config.yaml file by running the following command:
```
$ openshift-install create install-config --dir <installation_directory>
```
where <installation_directory> is the directory in which the installation program creates files.
Edit the install-config.yaml configuration file so that it contains the credentialsMode parameter set to Manual.
Example install-config.yaml configuration file
```
apiVersion: v1
baseDomain: cluster1.example.com
credentialsMode: Manual (1)
compute:
- architecture: amd64
  hyperthreading: Enabled
...
```
1 This line is added to set the credentialsMode parameter to Manual.
To generate the manifests, run the following command from the directory that contains the installation program:
```
$ openshift-install create manifests --dir <installation_directory>
```
where <installation_directory> is the directory in which the installation program creates files.
From the directory that contains the installation program, obtain details of the OKD release image that your openshift-install binary is built to use by running the following command:
```
$ openshift-install version
```
Example output
```
release image quay.io/openshift-release-dev/ocp-release:4.y.z-x86_64
```

Locate all CredentialsRequest objects in this release image that target the cloud you are deploying on by running the following command:

$ oc adm release extract quay.io/openshift-release-dev/ocp-release:4.y.z-x86_64 \
  --credentials-requests \
  --cloud=azure

This command creates a YAML file for each CredentialsRequest object.

Sample CredentialsRequest object

apiVersion: cloudcredential.openshift.io/v1
kind: CredentialsRequest
metadata:
  name: <component-credentials-request>
  namespace: openshift-cloud-credential-operator
  ...
spec:
  providerSpec:
    apiVersion: cloudcredential.openshift.io/v1
    kind: AzureProviderSpec
    roleBindings:
    - role: Contributor
  ...

Create YAML files for secrets in the openshift-install manifests directory that you generated previously. The secrets must be stored using the namespace and secret name defined in the spec.secretRef for each CredentialsRequest object.

Sample CredentialsRequest object with secrets

apiVersion: cloudcredential.openshift.io/v1
kind: CredentialsRequest
metadata:
  name: <component-credentials-request>
  namespace: openshift-cloud-credential-operator
  ...
spec:
  providerSpec:
    apiVersion: cloudcredential.openshift.io/v1
    kind: AzureProviderSpec
    roleBindings:
    - role: Contributor
      ...
  secretRef:
    name: <component-secret>
    namespace: <component-namespace>
  ...

Sample Secret object

apiVersion: v1
kind: Secret
metadata:
  name: <component-secret>
  namespace: <component-namespace>
data:
  azure_subscription_id: <base64_encoded_azure_subscription_id>
  azure_client_id: <base64_encoded_azure_client_id>
  azure_client_secret: <base64_encoded_azure_client_secret>
  azure_tenant_id: <base64_encoded_azure_tenant_id>
  azure_resource_prefix: <base64_encoded_azure_resource_prefix>
  azure_resourcegroup: <base64_encoded_azure_resourcegroup>
  azure_region: <base64_encoded_azure_region>

Before upgrading a cluster that uses manually maintained credentials, you must ensure that the CCO is in an upgradeable state. For details, see the "Upgrading clusters with manually maintained credentials" section of the installation content for your cloud provider.

Upgrading clusters with manually maintained credentials

The Cloud Credential Operator (CCO) Upgradable status for a cluster with manually maintained credentials is False by default.

For minor releases, for example, from 4.8 to 4.9, this status prevents you from upgrading until you have addressed any updated permissions and annotated the CloudCredential resource to indicate that the permissions are updated as needed for the next version. This annotation changes the Upgradable status to True.
For z-stream releases, for example, from 4.9.0 to 4.9.1, no permissions are added or changed, so the upgrade is not blocked.

Before upgrading a cluster with manually maintained credentials, you must create any new credentials for the release image that you are upgrading to. Additionally, you must review the required permissions for existing credentials and accommodate any new permissions requirements in the new release for those components.

Procedure

Extract and examine the CredentialsRequest custom resource for the new release.

The "Manually creating IAM" section of the installation content for your cloud provider explains how to obtain and use the credentials required for your cloud.
Update the manually maintained credentials on your cluster:
- Create new secrets for any CredentialsRequest custom resources that are added by the new release image.
- If the CredentialsRequest custom resources for any existing credentials that are stored in secrets have changed their permissions requirements, update the permissions as required.
When all of the secrets are correct for the new release, indicate that the cluster is ready to upgrade:
1. Log in to the OKD CLI as a user with the cluster-admin role.
2. Edit the CloudCredential resource to add an upgradeable-to annotation within the metadata field:
  $ oc edit cloudcredential cluster
  Text to add
  ... metadata: annotations: cloudcredential.openshift.io/upgradeable-to: <version_number> ...
  Where <version_number> is the version you are upgrading to, in the format x.y.z. For example, 4.8.2 for OKD 4.8.2.
  
  It may take several minutes after adding the annotation for the upgradeable status to change.
Verify that the CCO is upgradeable:
1. In the Administrator perspective of the web console, navigate to Administration → Cluster Settings.
2. To view the CCO status details, click cloud-credential in the Cluster Operators list.
3. If the Upgradeable status in the Conditions section is False, verify that the upgradeable-to annotation is free of typographical errors.

When the Upgradeable status in the Conditions section is True, you can begin the OKD upgrade.

Next steps

Install an OKD cluster on Azure Stack Hub with user-provisioned infrastructure by following Installing a cluster on Azure Stack Hub using ARM templates.