OpenShift Cluster Setup

This document walks you through using the automation scripts in this project to create an OpenShift cluster in Google Cloud.

Preparation

First, you should have a Red Hat account associated with your GitLab email. Contact our Red Hat Alliance liaison; they will arrange to send you an account invitation email. Once you activate your Red Hat account, you will have access to the licenses and subscriptions needed to run OpenShift.

To launch a cluster in Google Cloud, a public Cloud DNS zone must be connected to a registered domain and configured in Google Cloud DNS. If a domain is not already available, follow the steps in this guide to create one.

Get the CLI tools and Pull Secret

Two CLI tools are required to create an OpenShift cluster (openshift-install) and then interact with the cluster (oc).

A pull secret is required to fetch images from Red Hat’s private Docker registry. Every developer has a different pull secret associated with their Red Hat account.

To get the CLI tools and your pull secret, go to https://cloud.redhat.com/openshift/install/gcp/installer-provisioned and log in with your Red Hat account. On this page, download the latest version of the installer and command-line tools with the links provided. Extract these packages and place openshift-install and oc in your PATH.

Copy the pull secret to your clipboard and write the content to a file pull_secret in the root of this repository. This file is gitignored.

Create a Google Cloud (GCP) Service Account

Follow these instructions to create a Service Account in the Google Cloud cloud-native project. Attach all roles marked as Required in that document. Once the Service Account is created, generate a JSON key and save it as gcloud.json in the root of this repository. This file is gitignored.

Create your OpenShift cluster

Check configuration options below and ensure that required API services are enabled in the target GCP project. Run ./scripts/create_openshift_cluster.sh to create your OpenShift cluster in Google Cloud. This will be a 6 node cluster with 3 control plane (master) nodes and 3 worker nodes (configuration template). This takes around 40 minutes. Follow the instructions at the end of the console output to connect to the cluster.

Once created, you should be able to see your cluster registered here: https://cloud.redhat.com/openshift/. All installation logs and metadata will be stored in the install-$CLUSTER_NAME/ directory in this repository. This folder is gitignored.

If this cluster is meant to be used by other teammates or CI, create a new item in the 1Password Cloud Native vault and attach these files placed in INSTALL_DIR:

  • metadata.json, delete clusters as needed
  • auth/kubeconfig, authenticate to cluster
  • auth/kubeadmin-password, authenticate to cluster UI

Configuration options

Configuration can be applied during runtime by setting environment variables. All options have defaults, no options are required.

VariableDescriptionDefault
CLUSTER_NAMEName of clusterocp-$USER
BASE_DOMAINRoot domain for clusterk8s-ft.win
FIPS_ENABLEDEnable FIPS cryptography modulesfalse
GCP_PROJECT_IDGoogle Cloud project IDcloud-native-182609
GCP_REGIONGoogle Cloud region for clusterus-central1
GOOGLE_APPLICATION_CREDENTIALSPath to Google Cloud service account JSON filegcloud.json
GOOGLE_CREDENTIALSContent of Google Cloud service account JSON fileContent of $GOOGLE_APPLICATION_CREDENTIALS
PULL_SECRET_FILEPath to Red Hat pull secret filepull_secret
PULL_SECRETContent of Red Hat pull secret fileContent of $PULL_SECRET_FILE
SSH_PUBLIC_KEY_FILEPath to SSH public key file$HOME/.ssh/id_rsa.pub
SSH_PUBLIC_KEYContent of SSH public key fileContent of $SSH_PUBLIC_KEY_FILE
LOG_LEVELVerbosity of openshift-install outputinfo
note
The variables CLUSTER_NAME and BASE_DOMAIN are combined to build the domain name for the cluster.
note
Creating a cluster with FIPS_ENABLED set to true may cause issues with third party software. We are investigating this in this issue: https://gitlab.com/gitlab-org/charts/gitlab/-/issues/3153.

Destroy your OpenShift cluster

Run ./scripts/destroy_openshift_cluster.sh to destroy your OpenShift cluster in Google Cloud. This takes around 4 minutes.

The metadata.json file in INSTALL_DIR is all that is needed to destroy an OpenShift cluster. metadata.json files are attached to the cluster’s existing 1Password item that holds the cluster’s credentials.

Configuration options

Configuration can be applied during runtime by setting the following environment variables. All options have defaults, no options are required.

VariableDescriptionDefault
CLUSTER_NAMEName of clusterocp-$USER
LOG_LEVELVerbosity of openshift-install outputinfo
GOOGLE_APPLICATION_CREDENTIALSPath to Google Cloud service account JSON filegcloud.json
GOOGLE_CREDENTIALSContent of Google Cloud service account JSON fileContent of $GOOGLE_APPLICATION_CREDENTIALS

Next Steps

See doc/installation.md for instruction on installing the GitLab Operator in your OpenShift cluster.

Resources