diff --git a/access-ocp-api-through-cis.md b/access-ocp-api-through-cis.md new file mode 100644 index 00000000..efa804ca --- /dev/null +++ b/access-ocp-api-through-cis.md @@ -0,0 +1,114 @@ +# Configuring access to an application deployed on Red Hat OpenShift through CIS + +Hosting web applications is a common deployment pattern for public cloud. You can use Cloud Internet Services to provide secure access over the internet to your application deployed in a Red Hat OpenShift cluster. + + +## Before you begin + +- You need a Red Hat OpenShift cluster on IBM Cloud with an app deployed in the cluster. For more information, see [Deploying apps in Red Hat OpenShift clusters](https://cloud.ibm.com/docs/openshift?topic=openshift-deploy_app&interface=ui). +- You also need an instance of Cloud Internet Services with an active domain name. You can use this [CIS module](https://github.com/terraform-ibm-modules/terraform-ibm-cis) to create and configure the instance. +- Make sure that you have the [OpenShift CLI installed](https://cloud.ibm.com/docs/openshift?topic=openshift-cli-install). +- Make sure that you have the [IBM Cloud CLI installed](https://cloud.ibm.com/docs/cli?topic=cli-getting-started). + +## Add a DNS entry + +1. Log in to [IBM Cloud](https://cloud.ibm.com) and click your CIS instance under "Resources List". Navigate to the DNS tab under Reliability. +1. Go to `DNS records` and add a record: + + ```text + Type: CNAME + Name: + TTL: Automatic + Alias domain name: ## example: router-default.xxx-3b5bf5f75xxxx21c8c35ad277-0000.us-south.containers.appdomain.cloud + ``` + + Make a note of the CIS domain and DNS record name. You need it later to access the application from CIS. + + For example, the CIS domain is `example.com`, the DNS record name is `test`, and the application endpoint is `/healthz`. The URL to access will be `https://test.example.com/healthz`. If you try to connect to your URL, you get an SSL handshake error because the SSL certificates are not yet set up. + +## Configuring your SSL certificate + +To establish a secure connection between the client and server, you need to an SSL certificate. You can generate the certificate can be generated by using IBM Cloud [Secrets Manager](https://cloud.ibm.com/catalog/services/secrets-manager). + +1. Order a certificate in Secrets Manager: + + 1. Open the Secrets Manager service and select `Secrets` on the left. + 1. Click **Add**. + 1. If you are using a new Secrets Manager instance, you need to configure it before you order your certificate. Follow the steps that are outlined under [Preparing to order public certificates](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-prepare-order-certificates&interface=ui). + 1. Click **Public certificate**, and then click **Next**. + 1. Complete the form. Add a name and description. + 1. Click **Next**. + 1. Select your configured Let's Encrypt certificate authority engine. + 1. Select the key algorithm to use to generate the key for your certificate. + 1. Enable advanced options for the certificate. + - Make sure that the bundle is toggled off. + - Make sure that the automatic certificate rotation is toggled off. + 1. Select your configured DNS provider instance. + 1. Add the domains to include in your request. Check the subdomain, and then click **Done**. + 1. Click **Next**. + 1. Review your selections and click **Add**. +1. Download the certificates in Secrets Manager. It has `.key` and `.pem` file. +1. Run the following commands on the command line to create secrets in your cluster that use the downloaded certificates. + + ```sh + ibmcloud login --apikey + ibmcloud oc cluster config -c --admin + oc project openshift-ingress #switch to the project where your application is deployed + oc create secret tls --cert= --key= + ``` + +## Create an ingress + +An ingress defines rules to allow external access to services in a cluster. You create an ingress for your URL. + +You create an ingress for the endpoint that uses the CIS CNAME as the host and the TLS secret that you generated in the previous step. + +1. Update the following configuration to match your domain, secret, path, service, and port. + Save the file with the name `ingress.yaml`. + + ```yaml + apiVersion: networking.k8s.io/v1 + kind: Ingress + metadata: + name: myingressresource + spec: + tls: + - hosts: + - test.example.com + secretName: + rules: + - host: test.example.com + http: + paths: + - path: /healthz + pathType: ImplementationSpecific + backend: + service: + name: router-internal-default + port: + number: 1936 + ``` +1. Apply the configuration by running the following OpenShift CLI command: + + ```sh + oc apply -f ingress.yaml + ``` + + The command creates the route for the endpoint. + + You can validate the route by running the following command: + + ```sh + oc get routes + ``` +1. Verify that you can access your application at the endpoint that you created in [Add a DNS entry](#add-a-dns-entry). For example, + + ```sh + curl https://test.example.com/healthz + ok + ``` + + If you have issues connecting to the endpoint, see [Troubleshooting your CIS network connection](https://cloud.ibm.com/docs/cis?topic=cis-troubleshoot-your-cis-network-connection) for possible solutions. + + +You created a secure connection to your application endpoint through CIS. diff --git a/examples/complete/README.md b/examples/complete/README.md index d9acc152..d851534a 100644 --- a/examples/complete/README.md +++ b/examples/complete/README.md @@ -6,3 +6,6 @@ An end-to-end example that provisions the following infrastructure: - Adds a domain to the CIS instance. - Adds DNS records to the CIS instance. - Adds a global load balancer including the origin pools and health checks to the CIS instance. + + +For information about accessing an application through CIS, see [Configuring access to an application deployed on Red Hat OpenShift through CIS](./../../access-ocp-api-through-cis.md).