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+
»Download Helm chart
If you have not already done so, download the latest official consul-helm chart now.
$ helm repo add hashicorp https://helm.releases.hashicorp.com"hashicorp" has been added to your repositories
»Verify chart version
To ensure you have version
0.34.1 of the Helm chart, search your local repo.
$ helm search repo hashicorp/consulNAME CHART VERSION APP VERSION DESCRIPTIONhashicorp/consul 0.34.1 1.10.2 Official HashiCorp Consul Chart
If the correct version is not displayed in the output, try updating your helm repo.
$ helm repo updateHang tight while we grab the latest from your chart repositories......Successfully got an update from the "hashicorp" chart repository
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 setupINFO Checking if oc binary is cachedINFO Checking if podman remote binary is cachedINFO Checking if goodhosts binary is cachedINFO Checking if CRC bundle is cached in '$HOME/.crc'INFO Checking minimum RAM requirementsINFO Checking if running as non-rootINFO Checking if HyperKit is installedINFO Checking if crc-driver-hyperkit is installedINFO Checking file permissions for /etc/hostsINFO Checking file permissions for /etc/resolver/testingSetup 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 startINFO Checking if oc binary is cachedINFO Checking if podman remote binary is cachedINFO Checking if goodhosts binary is cachedINFO Checking minimum RAM requirementsINFO Checking if running as non-rootINFO Checking if HyperKit is installedINFO Checking if crc-driver-hyperkit is installedINFO Checking file permissions for /etc/hostsINFO 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:6443Login 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-infoKubernetes master is running at https://api.crc.testing:6443 To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.
Consul on Kubernetes provides a Helm chart to deploy a Consul datacenter on Kubernetes in a highly customized configuration. Review the docs on Helm chart Configuration to learn more about the available configurations.
»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 consulNow 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
»Import Consul and Consul on Kubernetes 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.10.3-ubi --from=registry.connect.redhat.com/hashicorp/consul:1.10.3-ubi --confirm$ oc import-image hashicorp/consul-k8s-control-plane:0.34.0-ubi --from=registry.connect.redhat.com/hashicorp/consul-k8s-control-plane:0.34.0-ubi --confirm
»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 << EOFglobal: name: consul datacenter: dc1 image: registry.connect.redhat.com/hashicorp/consul:1.10.3-ubi imageK8S: registry.connect.redhat.com/hashicorp/consul-k8s-control-plane:0.34.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: trueEOF
»Install Consul with Helm
Now, issue the
helm install command. The following command specifies that the
- Use the custom values file you created in the last step
- Use the
hashicorp/consulchart you downloaded earlier
- Set your Consul installation name to
consul-helmchart version 0.34.1
$ helm install -f config.yaml consul hashicorp/consul --version "0.34.1" --wait
The output will be similar to the following.
NAME: hashicorp... $ helm status hashicorp $ helm get all hashicorp
kubectl get pods to verify your installation.
$ watch kubectl get podsNAME READY STATUS RESTARTS AGEconsul-c74zv 1/1 Running 0 10mconsul-connect-injector-webhook-deployment-5f7d4cd45-vxmsl 1/1 Running 0 10mconsul-controller-7c884544f8-nj9lt 1/1 Running 0 10mconsul-server-0 1/1 Running 0 10mconsul-webhook-cert-manager-7fcf99885-rqmm6 1/1 Running 0 10m
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 8500:8500Forwarding from 127.0.0.1:8500 -> 8500Forwarding 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 membersNode Address Status Type Build Protocol DC Segmentconsul-server-0 10.116.0.78:8301 alive server 1.10.3 2 dc1 <all>crc-j55b9-master-0 10.116.0.77:8301 alive client 1.10.3 2 dc1 <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.