Red Hat OpenShift is a distribution of the Kubernetes platform that provides a number of usability and security enhancements.
In this tutorial you will:
- Deploy an OpenShift cluster
- Deploy a Consul datacenter
- Access the Consul UI
- Use the Consul CLI to inspect your environment
- Decommission the OpenShift environment
Security Warning This tutorial is not for production use. The chart was installed with an insecure configuration of Consul. Refer to the Secure Consul and Registered Services on Kubernetes tutorial to learn how you can secure Consul on Kubernetes in production.
To complete this tutorial you will need:
- Access to a Kubernetes cluster deployed with OpenShift
- A text editor
- Basic command line access
- A Red Hat account
- The Consul CLI
- CodeReady Containers v1.17.0+
- Helm v3.2.1+ or consul-k8s v0.39.0+
OpenShift can be deployed on multiple platforms, and there are several installation options available for installing OpenShift on either production and development environments. This tutorial requires a running OpenShift cluster to deploy Consul on Kubernetes. If an OpenShift cluster is already provisioned in a production or development environment to be used for deploying Consul on Kubernetes, please skip ahead to Deploy Consul. This tutorial will utilize CodeReady Containers (CRC) to provide a pre-configured development OpenShift environment on your local machine. CRC is bundled as a Red Hat Enterprise Linux virtual machine that supports native hypervisors for Linux, macOS, and Windows 10. CRC is the quickest way to get started building OpenShift clusters. It is designed to run on a local computer to simplify setup and emulate the cloud development environment locally with all the tools needed to develop container-based apps. While we use CRC in this tutorial, the Consul Helm deployment process will work on any OpenShift cluster and is production ready.
If deploying CRC is not preferred, a managed OpenShift cluster could quickly be provisioned within less than an hour using Azure RedHat OpenShift. Azure RedHat Openshift requires an Azure subscription. However, it provides the simplest installation flow for getting a production-ready OpenShift cluster available to be used for this tutorial.
After installing CodeReady Containers, issue the following command to setup your environment.
$ crc setup INFO Checking if oc binary is cached INFO Checking if podman remote binary is cached INFO Checking if goodhosts binary is cached INFO Checking if CRC bundle is cached in '$HOME/.crc' INFO Checking minimum RAM requirements INFO Checking if running as non-root INFO Checking if HyperKit is installed INFO Checking if crc-driver-hyperkit is installed INFO Checking file permissions for /etc/hosts INFO Checking file permissions for /etc/resolver/testing Setup is complete, you can now run 'crc start' to start the OpenShift cluster
Once the setup is complete, you can start the CRC service with the following command. The command will perform a few system checks to ensure your system meets the minimum requirements and will then ask you to provide an image pull secret. You should have your Red Hat account open so that you can easily copy your image pull secret when prompted.
$ crc start INFO Checking if oc binary is cached INFO Checking if podman remote binary is cached INFO Checking if goodhosts binary is cached INFO Checking minimum RAM requirements INFO Checking if running as non-root INFO Checking if HyperKit is installed INFO Checking if crc-driver-hyperkit is installed INFO Checking file permissions for /etc/hosts INFO Checking file permissions for /etc/resolver/testing ? Image pull secret [? for help]
Next, paste the image pull secret into the terminal and press enter.
INFO Loading bundle: crc_hyperkit_4.5.14.crcbundle ... INFO Checking size of the disk image /Users/derekstrickland/.crc/cache/crc_hyperkit_4.5.14/crc.qcow2 ... ...TRUNCATED... To access the cluster, first set up your environment by following 'crc oc-env' instructions. Then you can access it by running 'oc login -u developer -p developer https://api.crc.testing:6443'. To login as an admin, run 'oc login -u kubeadmin -p <redacted> https://api.crc.testing:6443'. To access the cluster, first set up your environment by following 'crc oc-env' instructions. You can now run 'crc console' and use these credentials to access the OpenShift web console.
Notice that the output instructs you to configure your
oc-env, and also includes
a login command and secret password. The secret is specific to your installation.
Make note of this command, as you will use it to login to CRC on your development
»Configure CRC environment
Next, configure the environment as instructed by CRC using the following command.
$ eval $(crc oc-env)
»Login to the OpenShift cluster
Next, use the login command you made note of before to authenticate with the OpenShift cluster.
Note You will have to replace the secret password below with the value output by CRC.
$ oc login -u kubeadmin -p <redacted> https://api.crc.testing:6443 Login successful. You have access to 57 projects, the list has been suppressed. You can list all projects with 'oc projects' Using project "default".
Validate that your CRC setup was successful with the following command.
$ kubectl cluster-info Kubernetes master is running at https://api.crc.testing:6443 To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.
»Create a new project
First, create an OpenShift project to install Consul on Kubernetes. Creating an OpenShift project creates a Kubernetes namespace to deploy Kubernetes resources.
$ oc new-project consul Now using project "consul" on server "https://api.crc.testing:6443". You can add applications to this project with the 'new-app' command. For example, try: oc new-app ruby~https://github.com/sclorg/ruby-ex.git to build a new example application in Ruby. Or use kubectl to deploy a simple Kubernetes application: kubectl create deployment hello-node --image=gcr.io/hello-minikube-zero-install/hello-node
»Create an image pull secret for a RedHat Registry service account
You must create an image pull secret before authenticating to the RedHat Registry and pulling images from the container registry. You must first create a registry service account on the RedHat Customer Portal, and then apply the OpenShift secret that is associated with the registry service account as shown below:
$ kubectl create -f openshift-secret.yml --namespace=consul secret/15490118-openshift-secret-secret created
In the Helm chart values file, use the output of previous command and update the attribute
imagePullSecrets stanza with its value.
»Helm chart configuration
To customize your deployment, you can pass a YAML configuration file to be used during the deployment.
Any values specified in the values file will override the Helm chart's default settings.
The following example file sets the
global.openshift.enabled entry to true,
which is required to operate Consul on OpenShift. Use this command to generate a
config.yaml that you will reference in the
helm install command later.
$ cat > config.yaml << EOF global: name: consul datacenter: dc1 image: registry.connect.redhat.com/hashicorp/consul:1.12.0-ubi imageK8S: registry.connect.redhat.com/hashicorp/consul-k8s-control-plane:0.43.0-ubi imagePullSecrets: - name: <Insert image pull secret name for RedHat Registry Service Account> openshift: enabled: true server: replicas: 1 bootstrapExpect: 1 disruptionBudget: enabled: true maxUnavailable: 0 client: enabled: true grpc: true ui: enabled: true connectInject: enabled: true default: true controller: enabled: true EOF
»Verify chart version
To ensure you have version
0.43.0 of the Helm chart, search your local repo.
$ helm search repo hashicorp/consul NAME CHART VERSION APP VERSION DESCRIPTION hashicorp/consul 0.43.0 1.12.0 Official HashiCorp Consul Chart
If the correct version is not displayed in the output, try updating your helm repo.
$ helm repo update Hang tight while we grab the latest from your chart repositories... ...Successfully got an update from the "hashicorp" chart repository
»Import images from RedHat Catalog (Optional)
Instead of pulling images directly from the RedHat Registry, Consul and Consul on Kubernetes images could also be pre-loaded onto the internal OpenShift registry using the
oc import command. Read more about importing images into the internal OpenShift Registry in the RedHat OpenShift cookbook
$ oc import-image hashicorp/consul:1.12.0-ubi --from=registry.connect.redhat.com/hashicorp/consul:1.12.0-ubi --confirm $ oc import-image hashicorp/consul-k8s-control-plane:0.43.0-ubi --from=registry.connect.redhat.com/hashicorp/consul-k8s-control-plane:0.43.0-ubi --confirm
»Install Consul in your cluster
You can now deploy a complete Consul datacenter in your Kubernetes cluster using the official Consul Helm chart or the Consul K8S CLI.
Now, issue the
helm install command. The following command specifies that the
- Use the custom values file you created earlier
- Use the
hashicorp/consulchart you downloaded in the last step
- Set your Consul installation name to
- Create Consul resources in the
$ helm install consul hashicorp/consul --values config.yaml --create-namespace --namespace consul --version "0.43.0" --wait
The output will be similar to the following.
NAME: consul LAST DEPLOYED: Sat Apr 23 11:00:16 2022 NAMESPACE: consul STATUS: deployed REVISION: 1 NOTES: Thank you for installing HashiCorp Consul! Your release is named consul. To learn more about the release, run: $ helm status consul $ helm get all consul Consul on Kubernetes Documentation: https://www.consul.io/docs/platform/k8s Consul on Kubernetes CLI Reference: https://www.consul.io/docs/k8s/k8s-cli
kubectl get pods to verify your installation.
$ watch kubectl get pods --namespace consul NAME READY STATUS RESTARTS AGE consul-client-477vv 1/1 Running 0 6m consul-connect-injector-5f485f9cb6-8fvkh 1/1 Running 0 6m consul-connect-injector-5f485f9cb6-s97m5 1/1 Running 0 6m consul-controller-5cc8d5867-vqh5l 1/1 Running 0 6m consul-server-0 1/1 Running 0 6m consul-webhook-cert-manager-5cf7f8d655-k7ktd 1/1 Running 0 6m
Once all pods have a status of
CTRL-C to stop the watch.
»Accessing the Consul UI
Now that Consul has been deployed, you can access the Consul UI to verify that the Consul installation was successful, and that the environment is healthy.
»Expose the UI service to the host
Since the application is running on your local development host, you can expose
the Consul UI to the development host using
kubectl port-forward. The UI and the
HTTP API Server run on the
consul-server-0 pod. Issue the following command to
expose the server endpoint at port
8500 to your local development host.
$ kubectl port-forward consul-server-0 --namespace consul 8500:8500 Forwarding from 127.0.0.1:8500 -> 8500 Forwarding from [::1]:8500 -> 8500
http://localhost:8500 in a new browser tab, and you should observe a
page that looks similar to the following.
»Accessing Consul with the CLI and HTTP API
To access Consul with the CLI, set the
CONSUL_HTTP_ADDR following environment variable on the development host so that the Consul CLI knows which Consul server to interact with.
$ export CONSUL_HTTP_ADDR=http://127.0.0.1:8500
You should be able to issue the
consul members command to view all available
Consul datacenter members.
$ consul members Node Address Status Type Build Protocol DC Partition Segment consul-server-0 10.217.0.106:8301 alive server 1.12.0 2 dc1 default <all> crc-dzk9v-master-0 10.217.0.104:8301 alive client 1.12.0 2 dc1 default <default>
You can use the same URL to make HTTP API requests with your custom code.
»Decommission the environment
Now that you have completed the tutorial, you should decommission the CRC environment.
CTRL-C in the terminal to stop the port forwarding process.
First, stop the running cluster.
$ crc stop
INFO Stopping the OpenShift cluster, this may take a few minutes... Stopped the OpenShift cluster
Next, issue the following command to delete the cluster.
$ crc delete
The CRC CLI will ask you to confirm that you want to delete the cluster.
Do you want to delete the OpenShift cluster? [y/N]:
y to confirm.
Deleted the OpenShift cluster
In this tutorial you created a Red Hat OpenShift cluster, and installed Consul to the cluster.
- Deployed an OpenShift cluster
- Deployed a Consul datacenter
- Accessed the Consul UI
- Used the Consul CLI to inspect your environment
- Decommissioned the environment
It is highly recommended that you properly secure your Kubernetes cluster and that you understand and enable the recommended security features of Consul. Refer to the Secure Consul and Registered Services on Kubernetes tutorial to learn how you can deploy an example workload, and secure Consul on Kubernetes for production.
For more information on the Consul Helm chart configuration options, review the consul-helm chart documentation.