vCPU
In OpenShift Container Platform version 4.10, you can install a cluster on Microsoft Azure by using infrastructure that you provide.
Several Azure Resource Manager (ARM) templates are provided to assist in completing these steps or to help model your own.
The steps for performing a user-provisioned infrastructure installation are provided as an example only. Installing a cluster with infrastructure you provide requires knowledge of the cloud provider and the installation process of OpenShift Container Platform. Several ARM templates are provided to assist in completing these steps or to help model your own. You are also free to create the required resources through other methods; the templates are just an example. |
You reviewed details about the OpenShift Container Platform installation and update processes.
You read the documentation on selecting a cluster installation method and preparing it for users.
You configured an Azure account to host the cluster.
You downloaded the Azure CLI and installed it on your computer. See Install the Azure CLI in the Azure documentation. The documentation below was last tested using version 2.2.0
of the Azure CLI. Azure CLI commands might perform differently based on the version you use.
If you use a firewall and plan to use the Telemetry service, you configured the firewall to allow the sites that your cluster requires access to.
If the cloud identity and access management (IAM) APIs are not accessible in your environment, or if you do not want to store an administrator-level credential secret in the kube-system
namespace, you can manually create and maintain IAM credentials.
Be sure to also review this site list if you are configuring a proxy. |
In OpenShift Container Platform 4.10, you require access to the internet to install your cluster.
You must have internet access to:
Access OpenShift Cluster Manager to download the installation program and perform subscription management. If the cluster has internet access and you do not disable Telemetry, that service automatically entitles your cluster.
Access Quay.io to obtain the packages that are required to install your cluster.
Obtain the packages that are required to perform cluster updates.
If your cluster cannot have direct internet access, you can perform a restricted network installation on some types of infrastructure that you provision. During that process, you download the required content and use it to populate a mirror registry with the installation packages. With some installation types, the environment that you install your cluster in will not require internet access. Before you update the cluster, you update the content of the mirror registry. |
Before you can install OpenShift Container Platform, you must configure an Azure project to host it.
All Azure resources that are available through public endpoints are subject to resource name restrictions, and you cannot create resources that use certain terms. For a list of terms that Azure restricts, see Resolve reserved resource name errors in the Azure documentation. |
The OpenShift Container Platform cluster uses a number of Microsoft Azure components, and the default Azure subscription and service limits, quotas, and constraints affect your ability to install OpenShift Container Platform clusters.
Default limits vary by offer category types, such as Free Trial and Pay-As-You-Go, and by series, such as Dv2, F, and G. For example, the default for Enterprise Agreement subscriptions is 350 cores. Check the limits for your subscription type and if necessary, increase quota limits for your account before you install a default cluster on Azure. |
The following table summarizes the Azure components whose limits can impact your ability to install and run OpenShift Container Platform clusters.
Component | Number of components required by default | Default Azure limit | Description | ||||||
---|---|---|---|---|---|---|---|---|---|
vCPU |
40 |
20 per region |
A default cluster requires 40 vCPUs, so you must increase the account limit. By default, each cluster creates the following instances:
Because the bootstrap machine uses To deploy more worker nodes, enable autoscaling, deploy large workloads, or use a different instance type, you must further increase the vCPU limit for your account to ensure that your cluster can deploy the machines that you require. By default, the installation program distributes control plane and compute machines across all availability zones within a region. To ensure high availability for your cluster, select a region with at least three availability zones. If your region contains fewer than three availability zones, the installation program places more than one control plane machine in the available zones. |
||||||
OS Disk |
7 |
VM OS disk must be able to sustain a minimum throughput of 5000 IOPS / 200MBps. This throughput can be provided by having a minimum of 1 TiB Premium SSD (P30). In Azure, disk performance is directly dependent on SSD disk sizes, so to achieve the throughput supported by Host caching must be set to |
|||||||
VNet |
1 |
1000 per region |
Each default cluster requires one Virtual Network (VNet), which contains two subnets. |
||||||
Network interfaces |
7 |
65,536 per region |
Each default cluster requires seven network interfaces. If you create more machines or your deployed workloads create load balancers, your cluster uses more network interfaces. |
||||||
Network security groups |
2 |
5000 |
Each cluster creates network security groups for each subnet in the VNet. The default cluster creates network security groups for the control plane and for the compute node subnets:
|
||||||
Network load balancers |
3 |
1000 per region |
Each cluster creates the following load balancers:
If your applications create more Kubernetes |
||||||
Public IP addresses |
3 |
Each of the two public load balancers uses a public IP address. The bootstrap machine also uses a public IP address so that you can SSH into the machine to troubleshoot issues during installation. The IP address for the bootstrap node is used only during installation. |
|||||||
Private IP addresses |
7 |
The internal load balancer, each of the three control plane machines, and each of the three worker machines each use a private IP address. |
|||||||
Spot VM vCPUs (optional) |
0 If you configure spot VMs, your cluster must have two spot VM vCPUs for every compute node. |
20 per region |
This is an optional component. To use spot VMs, you must increase the Azure default limit to at least twice the number of compute nodes in your cluster.
|
To install OpenShift Container Platform, the Microsoft Azure account you use must have a dedicated public hosted DNS zone in your account. This zone must be authoritative for the domain. This service provides cluster DNS resolution and name lookup for external connections to the cluster.
Identify your domain, or subdomain, and registrar. You can transfer an existing domain and registrar or obtain a new one through Azure or another source.
For more information about purchasing domains through Azure, see Buy a custom domain name for Azure App Service in the Azure documentation. |
If you are using an existing domain and registrar, migrate its DNS to Azure. See Migrate an active DNS name to Azure App Service in the Azure documentation.
Configure DNS for your domain. Follow the steps in the Tutorial: Host your domain in Azure DNS in the Azure documentation to create a public hosted zone for your domain or subdomain, extract the new authoritative name servers, and update the registrar records for the name servers that your domain uses.
Use an appropriate root domain, such as openshiftcorp.com
, or subdomain,
such as clusters.openshiftcorp.com
.
If you use a subdomain, follow your company’s procedures to add its delegation records to the parent domain.
You can view Azure’s DNS solution by visiting this example for creating DNS zones.
To increase an account limit, file a support request on the Azure portal.
You can increase only one type of quota per support request. |
From the Azure portal, click Help + support in the lower left corner.
Click New support request and then select the required values:
From the Issue type list, select Service and subscription limits (quotas).
From the Subscription list, select the subscription to modify.
From the Quota type list, select the quota to increase. For example, select Compute-VM (cores-vCPUs) subscription limit increases to increase the number of vCPUs, which is required to install a cluster.
Click Next: Solutions.
On the Problem Details page, provide the required information for your quota increase:
Click Provide details and provide the required details in the Quota details window.
In the SUPPORT METHOD and CONTACT INFO sections, provide the issue severity and your contact details.
Click Next: Review + create and then click Create.
Because your cluster has limited access to automatic machine management when you use infrastructure that you provision, you must provide a mechanism for approving cluster certificate signing requests (CSRs) after installation. The kube-controller-manager
only approves the kubelet client CSRs. The machine-approver
cannot guarantee the validity of a serving certificate that is requested by using kubelet credentials because it cannot confirm that the correct machine issued the request. You must determine and implement a method of verifying the validity of the kubelet serving certificate requests and approving them.
OpenShift Container Platform needs a service principal so it can manage Microsoft Azure resources. Before you can create a service principal, your Azure account subscription must have the following roles:
User Access Administrator
Owner
To set roles on the Azure portal, see the Manage access to Azure resources using RBAC and the Azure portal in the Azure documentation.
Because OpenShift Container Platform and its installation program must create Microsoft Azure resources through Azure Resource Manager, you must create a service principal to represent it.
Install or update the Azure CLI.
Install the jq
package.
Your Azure account has the required roles for the subscription that you use.
Log in to the Azure CLI:
$ az login
Log in to Azure in the web console by using your credentials.
If your Azure account uses subscriptions, ensure that you are using the right subscription.
View the list of available accounts and record the tenantId
value for the
subscription you want to use for your cluster:
$ az account list --refresh
[
{
"cloudName": "AzureCloud",
"id": "9bab1460-96d5-40b3-a78e-17b15e978a80",
"isDefault": true,
"name": "Subscription Name",
"state": "Enabled",
"tenantId": "6057c7e9-b3ae-489d-a54e-de3f6bf6a8ee",
"user": {
"name": "you@example.com",
"type": "user"
}
}
]
View your active account details and confirm that the tenantId
value matches
the subscription you want to use:
$ az account show
{
"environmentName": "AzureCloud",
"id": "9bab1460-96d5-40b3-a78e-17b15e978a80",
"isDefault": true,
"name": "Subscription Name",
"state": "Enabled",
"tenantId": "6057c7e9-b3ae-489d-a54e-de3f6bf6a8ee", (1)
"user": {
"name": "you@example.com",
"type": "user"
}
}
1 | Ensure that the value of the tenantId parameter is the UUID of the
correct subscription. |
If you are not using the right subscription, change the active subscription:
$ az account set -s <id> (1)
1 | Substitute the value of the id for the subscription that you want to
use for <id> . |
If you changed the active subscription, display your account information again:
$ az account show
{
"environmentName": "AzureCloud",
"id": "33212d16-bdf6-45cb-b038-f6565b61edda",
"isDefault": true,
"name": "Subscription Name",
"state": "Enabled",
"tenantId": "8049c7e9-c3de-762d-a54e-dc3f6be6a7ee",
"user": {
"name": "you@example.com",
"type": "user"
}
}
Record the values of the tenantId
and id
parameters from the previous
output. You need these values during OpenShift Container Platform installation.
Create the service principal for your account:
$ az ad sp create-for-rbac --role Contributor --name <service_principal> (1)
1 | Replace <service_principal> with the name to assign to the service principal. |
Changing "<service_principal>" to a valid URI of "http://<service_principal>", which is the required format used for service principal names
Retrying role assignment creation: 1/36
Retrying role assignment creation: 2/36
Retrying role assignment creation: 3/36
Retrying role assignment creation: 4/36
{
"appId": "8bd0d04d-0ac2-43a8-928d-705c598c6956",
"displayName": "<service_principal>",
"name": "http://<service_principal>",
"password": "ac461d78-bf4b-4387-ad16-7e32e328aec6",
"tenant": "6048c7e9-b2ad-488d-a54e-dc3f6be6a7ee"
}
Record the values of the appId
and password
parameters from the previous
output. You need these values during OpenShift Container Platform installation.
Grant additional permissions to the service principal.
You must always add the Contributor
and User Access Administrator
roles to the app registration service principal so the cluster can assign credentials for its components.
To operate the Cloud Credential Operator (CCO) in mint mode, the app registration service principal also requires the Azure Active Directory Graph/Application.ReadWrite.OwnedBy
API permission.
To operate the CCO in passthrough mode, the app registration service principal does not require additional API permissions.
For more information about CCO modes, see "About the Cloud Credential Operator" in the "Managing cloud provider credentials" section of the Authentication and authorization guide.
If you limit the service principal scope of the OpenShift Container Platform installation program to an already existing Azure resource group, you must ensure all other resources used by the installation program in your environment have the necessary permissions, such as the public DNS zone and virtual network. Destroying a cluster using the installation program deletes this resource group. |
To assign the User Access Administrator
role, run the following command:
$ az role assignment create --role "User Access Administrator" \
--assignee-object-id $(az ad sp list --filter "appId eq '<appId>'" \ (1)
| jq '.[0].objectId' -r)
1 | Replace <appId> with the appId parameter value for your service principal. |
To assign the Azure Active Directory Graph
permission, run the following
command:
$ az ad app permission add --id <appId> \ (1)
--api 00000002-0000-0000-c000-000000000000 \
--api-permissions 824c81eb-e3f8-4ee6-8f6d-de7f50d565b7=Role
1 | Replace <appId> with the appId parameter value for your service principal. |
Invoking "az ad app permission grant --id 46d33abc-b8a3-46d8-8c84-f0fd58177435 --api 00000002-0000-0000-c000-000000000000" is needed to make the change effective
For more information about the specific permissions that you grant with this command, see the GUID Table for Windows Azure Active Directory Permissions.
Approve the permissions request. If your account does not have the Azure Active Directory tenant administrator role, follow the guidelines for your organization to request that the tenant administrator approve your permissions request.
$ az ad app permission grant --id <appId> \ (1)
--api 00000002-0000-0000-c000-000000000000
1 | Replace <appId> with the appId parameter value for your service principal. |
For more information about CCO modes, see About the Cloud Credential Operator.
The installation program dynamically generates the list of available Microsoft Azure regions based on your subscription.
australiacentral
(Australia Central)
australiaeast
(Australia East)
australiasoutheast
(Australia South East)
brazilsouth
(Brazil South)
canadacentral
(Canada Central)
canadaeast
(Canada East)
centralindia
(Central India)
centralus
(Central US)
eastasia
(East Asia)
eastus
(East US)
eastus2
(East US 2)
francecentral
(France Central)
germanywestcentral
(Germany West Central)
japaneast
(Japan East)
japanwest
(Japan West)
koreacentral
(Korea Central)
koreasouth
(Korea South)
northcentralus
(North Central US)
northeurope
(North Europe)
norwayeast
(Norway East)
southafricanorth
(South Africa North)
southcentralus
(South Central US)
southeastasia
(Southeast Asia)
southindia
(South India)
swedencentral
(Sweden Central)
switzerlandnorth
(Switzerland North)
uaenorth
(UAE North)
uksouth
(UK South)
ukwest
(UK West)
westcentralus
(West Central US)
westeurope
(West Europe)
westindia
(West India)
westus
(West US)
westus2
(West US 2)
westus3
(West US 3)
Support for the following Microsoft Azure Government (MAG) regions was added in OpenShift Container Platform version 4.6:
usgovtexas
(US Gov Texas)
usgovvirginia
(US Gov Virginia)
You can reference all available MAG regions in the Azure documentation. Other provided MAG regions are expected to work with OpenShift Container Platform, but have not been tested.
For a cluster that contains user-provisioned infrastructure, you must deploy all of the required machines.
This section describes the requirements for deploying OpenShift Container Platform on user-provisioned infrastructure.
The smallest OpenShift Container Platform clusters require the following hosts:
Hosts | Description |
---|---|
One temporary bootstrap machine |
The cluster requires the bootstrap machine to deploy the OpenShift Container Platform cluster on the three control plane machines. You can remove the bootstrap machine after you install the cluster. |
Three control plane machines |
The control plane machines run the Kubernetes and OpenShift Container Platform services that form the control plane. |
At least two compute machines, which are also known as worker machines. |
The workloads requested by OpenShift Container Platform users run on the compute machines. |
To maintain high availability of your cluster, use separate physical hosts for these cluster machines. |
The bootstrap and control plane machines must use Red Hat Enterprise Linux CoreOS (RHCOS) as the operating system. However, the compute machines can choose between Red Hat Enterprise Linux CoreOS (RHCOS), Red Hat Enterprise Linux (RHEL) 8.4, or RHEL 8.5.
Note that RHCOS is based on Red Hat Enterprise Linux (RHEL) 8 and inherits all of its hardware certifications and requirements. See Red Hat Enterprise Linux technology capabilities and limits.
Each cluster machine must meet the following minimum requirements:
Machine | Operating System | vCPU [1] | Virtual RAM | Storage | IOPS [2] |
---|---|---|---|---|---|
Bootstrap |
RHCOS |
4 |
16 GB |
100 GB |
300 |
Control plane |
RHCOS |
4 |
16 GB |
100 GB |
300 |
Compute |
RHCOS, RHEL 8.4, or RHEL 8.5 [3] |
2 |
8 GB |
100 GB |
300 |
One vCPU is equivalent to one physical core when simultaneous multithreading (SMT), or hyperthreading, is not enabled. When enabled, use the following formula to calculate the corresponding ratio: (threads per core × cores) × sockets = vCPUs.
OpenShift Container Platform and Kubernetes are sensitive to disk performance, and faster storage is recommended, particularly for etcd on the control plane nodes which require a 10 ms p99 fsync duration. Note that on many cloud platforms, storage size and IOPS scale together, so you might need to over-allocate storage volume to obtain sufficient performance.
As with all user-provisioned installations, if you choose to use RHEL compute machines in your cluster, you take responsibility for all operating system life cycle management and maintenance, including performing system updates, applying patches, and completing all other required tasks. Use of RHEL 7 compute machines is deprecated and has been removed in OpenShift Container Platform 4.10 and later.
You are required to use Azure virtual machines with |
Before you install OpenShift Container Platform, download the installation file on a local computer.
You have a computer that runs Linux or macOS, with 500 MB of local disk space
Access the Infrastructure Provider page on the OpenShift Cluster Manager site. If you have a Red Hat account, log in with your credentials. If you do not, create an account.
Select your infrastructure provider.
Navigate to the page for your installation type, download the installation program that corresponds with your host operating system and architecture, and place the file in the directory where you will store the installation configuration files.
The installation program creates several files on the computer that you use to install your cluster. You must keep the installation program and the files that the installation program creates after you finish installing the cluster. Both files are required to delete the cluster. |
Deleting the files created by the installation program does not remove your cluster, even if the cluster failed during installation. To remove your cluster, complete the OpenShift Container Platform uninstallation procedures for your specific cloud provider. |
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 the 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 OpenShift Container Platform components.
During an OpenShift Container Platform installation, you can provide an SSH public key to the installation program. The key is passed to the Red Hat Enterprise Linux CoreOS (RHCOS) nodes through their Ignition config files and is used to authenticate SSH access to the nodes. The key is added to the ~/.ssh/authorized_keys
list for the core
user on each node, which enables password-less authentication.
After the key is passed to the nodes, you can use the key pair to SSH in to the RHCOS nodes as the user core
. To access the nodes through SSH, the private key identity must be managed by SSH for your local user.
If you want to SSH in to your cluster nodes to perform installation debugging or disaster recovery, you must provide the SSH public key during the installation process. The ./openshift-install gather
command also requires the SSH public key to be in place on the cluster nodes.
Do not skip this procedure in production environments, where disaster recovery and debugging is required. |
You must use a local key, not one that you configured with platform-specific approaches such as AWS key pairs. |
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)
1 | Specify the path and file name, such as ~/.ssh/id_ed25519 , of the new SSH key. If you have an existing key pair, ensure your public key is in the your ~/.ssh directory. |
If you plan to install an OpenShift Container Platform cluster that uses FIPS Validated / Modules in Process cryptographic libraries on the |
View the public SSH key:
$ cat <path>/<file_name>.pub
For example, run the following to view the ~/.ssh/id_ed25519.pub
public key:
$ 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.
On some distributions, default SSH private key identities such as |
If the ssh-agent
process is not already running for your local user, start it as a background task:
$ eval "$(ssh-agent -s)"
Agent pid 31874
If your cluster is in FIPS mode, only use FIPS-compliant algorithms to generate the SSH key. The key must be either RSA or ECDSA. |
Add your SSH private key to the ssh-agent
:
$ ssh-add <path>/<file_name> (1)
1 | Specify the path and file name for your SSH private key, such as ~/.ssh/id_ed25519 |
Identity added: /home/<you>/<path>/<file_name> (<computer_name>)
When you install OpenShift Container Platform, provide the SSH public key to the installation program. If you install a cluster on infrastructure that you provision, you must provide the key to the installation program.
To install OpenShift Container Platform on Microsoft Azure using user-provisioned infrastructure, you must generate the files that the installation program needs to deploy your cluster and modify them so that the cluster creates only the machines that it will use. You generate and customize the install-config.yaml
file, Kubernetes manifests, and Ignition config files. You also have the option to first set up a separate var
partition during the preparation phases of installation.
/var
partitionIt is recommended that disk partitioning for OpenShift Container Platform be left to the installer. However, there are cases where you might want to create separate partitions in a part of the filesystem that you expect to grow.
OpenShift Container Platform supports the addition of a single partition to attach storage to either the /var
partition or a subdirectory of /var
. For example:
/var/lib/containers
: Holds container-related content that can grow as more images and containers are added to a system.
/var/lib/etcd
: Holds data that you might want to keep separate for purposes such as performance optimization of etcd storage.
/var
: Holds data that you might want to keep separate for purposes such as auditing.
Storing the contents of a /var
directory separately makes it easier to grow storage for those areas as needed and reinstall OpenShift Container Platform at a later date and keep that data intact. With this method, you will not have to pull all your containers again, nor will you have to copy massive log files when you update systems.
Because /var
must be in place before a fresh installation of Red Hat Enterprise Linux CoreOS (RHCOS), the following procedure sets up the separate /var
partition by creating a machine config manifest that is inserted during the openshift-install
preparation phases of an OpenShift Container Platform installation.
If you follow the steps to create a separate |