Installing a cluster on Azure Stack Hub with network customizations

If you do not have an existing SSH key pair on your local machine to use for authentication onto your cluster nodes, create one. For example, on a computer that uses a Linux operating system, run the following command:

$ ssh-keygen -t ed25519 -N '' -f <path>/<file_name> (1)

View the public SSH key:

$ cat <path>/<file_name>.pub

$ cat ~/.ssh/id_ed25519.pub

Add the SSH private key identity to the SSH agent for your local user, if it has not already been added. SSH agent management of the key is required for password-less SSH authentication onto your cluster nodes, or if you want to use the ./openshift-install gather command.

Add your SSH private key to the ssh-agent:

$ ssh-add <path>/<file_name> (1)

Identity added: /home/<you>/<path>/<file_name> (<computer_name>)

Obtain the FCOS VHD cluster image:

Decompress the VHD file.

Upload the local VHD to the Azure Stack Hub environment, making sure that the blob is publicly available. For example, you can upload the VHD to a blob using the az cli or the web portal.

Download the installation program from https://github.com/openshift/okd/releases.

Extract the installation program. For example, on a computer that uses a Linux operating system, run the following command:

$ tar -xvf openshift-install-linux.tar.gz

Download your installation pull secret from Red Hat OpenShift Cluster Manager. This pull secret allows you to authenticate with the services that are provided by the included authorities, including Quay.io, which serves the container images for OKD components.

Create an installation directory to store your required installation assets in:

$ mkdir <installation_directory>

Customize the sample install-config.yaml file template that is provided and save it in the <installation_directory>.

Back up the install-config.yaml file so that you can use it to install multiple clusters.

If you have not previously created installation manifest files, do so by running the following command:

$ openshift-install create manifests --dir <installation_directory>

Set a $RELEASE_IMAGE variable with the release image from your installation file by running the following command:

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

Extract the list of CredentialsRequest custom resources (CRs) from the OKD release image by running the following command:

$ oc adm release extract \
  --from=$RELEASE_IMAGE \
  --credentials-requests \
  --included \(1)
  --install-config=<path_to_directory_with_installation_configuration>/install-config.yaml \(2)
  --to=<path_to_directory_for_credentials_requests> (3)

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.

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>
  ...

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>

From the directory in which the installation program creates files, go to the manifests directory.

Add user-ca-bundle to the spec.trustedCA.name field.

apiVersion: config.openshift.io/v1
kind: Proxy
metadata:
  creationTimestamp: null
  name: cluster
spec:
  trustedCA:
    name: user-ca-bundle
status: {}

Optional: Back up the manifests/ cluster-proxy-01-config.yaml file. The installation program consumes the manifests/ directory when you deploy the cluster.

Change to the directory that contains the installation program and create the manifests:

$ ./openshift-install create manifests --dir <installation_directory> (1)

Create a stub manifest file for the advanced network configuration that is named cluster-network-03-config.yml in the <installation_directory>/manifests/ directory:

apiVersion: operator.openshift.io/v1
kind: Network
metadata:
  name: cluster
spec:

Specify the advanced network configuration for your cluster in the cluster-network-03-config.yml file, such as in the following example:

apiVersion: operator.openshift.io/v1
kind: Network
metadata:
  name: cluster
spec:
  defaultNetwork:
    ovnKubernetesConfig:
      ipsecConfig:
        mode: Full

Optional: Back up the manifests/cluster-network-03-config.yml file. The installation program consumes the manifests/ directory when you create the Ignition config files.

Change to the directory that contains the installation program and create the manifests:

$ ./openshift-install create manifests --dir <installation_directory>

Create a stub manifest file for the advanced network configuration that is named cluster-network-03-config.yml in the <installation_directory>/manifests/ directory:

$ cat <<EOF > <installation_directory>/manifests/cluster-network-03-config.yml
apiVersion: operator.openshift.io/v1
kind: Network
metadata:
  name: cluster
spec:
EOF

Open the cluster-network-03-config.yml file in an editor and configure OVN-Kubernetes with hybrid networking, as in the following example:

apiVersion: operator.openshift.io/v1
kind: Network
metadata:
  name: cluster
spec:
  defaultNetwork:
    ovnKubernetesConfig:
      hybridOverlayConfig:
        hybridClusterNetwork: (1)
        - cidr: 10.132.0.0/14
          hostPrefix: 23
        hybridOverlayVXLANPort: 9898 (2)

Save the cluster-network-03-config.yml file and quit the text editor.

Optional: Back up the manifests/cluster-network-03-config.yml file. The installation program deletes the manifests/ directory when creating the cluster.

Navigate to https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/ and choose the folder for your operating system and architecture.

Download oc.tar.gz.

Unpack the archive:

$ tar xvf <file>

Place the oc binary in a directory that is on your PATH.

$ echo $PATH

Navigate to https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/ and choose the folder for your operating system and architecture.

Download oc.zip.

Unzip the archive with a ZIP program.

Move the oc binary to a directory that is on your PATH.

C:\> path

Navigate to https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/ and choose the folder for your operating system and architecture.

Download oc.tar.gz.

Unpack and unzip the archive.

Move the oc binary to a directory on your PATH.

$ echo $PATH

Export the kubeadmin credentials:

$ export KUBECONFIG=<installation_directory>/auth/kubeconfig (1)

Verify you can run oc commands successfully using the exported configuration:

$ oc whoami

system:admin

Obtain the password for the kubeadmin user from the kubeadmin-password file on the installation host:

$ cat <installation_directory>/auth/kubeadmin-password

List the OKD web console route:

$ oc get routes -n openshift-console | grep 'console-openshift'

console     console-openshift-console.apps.<cluster_name>.<base_domain>            console     https   reencrypt/Redirect   None

Navigate to the route detailed in the output of the preceding command in a web browser and log in as the kubeadmin user.