diff --git a/.github/workflows/build-test.yml b/.github/workflows/build-test.yml index bff9d85..46d8089 100644 --- a/.github/workflows/build-test.yml +++ b/.github/workflows/build-test.yml @@ -32,7 +32,7 @@ jobs: uses: actions/checkout@v2 - name: Set up Cloud SDK - uses: google-github-actions/setup-gcloud@master + uses: google-github-actions/setup-gcloud@v0 with: project_id: ${{ secrets.GCP_PROJECT_ID }} service_account_key: ${{ secrets.GCP_SA_KEY }} diff --git a/README.md b/README.md index b5e97da..7f7aae2 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,8 @@ The PubSub+ deployment does not require any special OpenShift Security Context; We recommend using the PubSub+ Helm chart for convenience. An alternative method [using OpenShift templates](/docs/PubSubPlusOpenShiftDeployment.md#step-4-option-2-deploy-using-openshift-templates) is also available. +> Deprecation warning: deploying using OpenShift Templates is being phased out and the templates in this quickstart will be no longer maintained. The recommended deployment method is to use Helm. If Helm cannot be used then refer to the [PubSub+ Kubernetes documentation](https://github.com/SolaceProducts/pubsubplus-kubernetes-quickstart/blob/master/docs/PubSubPlusK8SDeployment.md#alternative-deployment-with-generating-templates-for-the-kubernetes-kubectl-tool) to generate deployment manifests. + ## Pre-requisite: Access to OpenShift Platform There are [multiple ways](https://www.openshift.com/try ) to get to an OpenShift 4 platform: @@ -24,7 +26,6 @@ There are [multiple ways](https://www.openshift.com/try ) to get to an OpenShift - An option for developers is to locally deploy an all-in-one environment using [CodeReady Containers](https://developers.redhat.com/products/codeready-containers/overview). - An easy way to get an OpenShift cluster up and running is through the [Developer Sandbox](https://developers.redhat.com/developer-sandbox) program. You can sign up for a free 14-day trial. - ## Deploying PubSub+ Software Event Broker The event broker can be deployed in either a three-node High-Availability (HA) group, or as a single-node standalone deployment. For simple test environments that need only to validate application functionality, a single instance will suffice. Note that in production, or any environment where message loss cannot be tolerated, an HA deployment is required. @@ -32,9 +33,9 @@ The event broker can be deployed in either a three-node High-Availability (HA) g In this quick start we go through the steps to set up an event broker using [Solace PubSub+ Helm charts](https://artifacthub.io/packages/search?page=1&repo=solace). There are three Helm chart variants available with default small-size configurations: -- `pubsubplus-openshift-dev` - deploys a minimum footprint software event broker for developers (standalone) -- `pubsubplus-openshift` - deploys a standalone software event broker that supports 100 connections -- `pubsubplus-openshift-ha` - deploys three software event brokers in an HA group that supports 100 connections +- `solace-pubsubplus-openshift-dev` - deploys a minimum footprint software event broker for developers (standalone) +- `solace-pubsubplus-openshift` - deploys a standalone software event broker that supports 100 connections +- `solace-pubsubplus-openshift-ha` - deploys three software event brokers in an HA group that supports 100 connections For other event broker configurations or sizes, refer to the [PubSub+ Software Event Broker Helm Chart](https://github.com/SolaceProducts/pubsubplus-kubernetes-quickstart/blob/master/pubsubplus/README.md) documentation. @@ -47,6 +48,7 @@ You can install Helm charts on an OpenShift Container Platform cluster using the This simple method uses the OpenShift Web Console graphical interface: * In a browser open the OpenShift Web Console, Developer perspective. +* Ensure not to use the `default` project, create a new project if required. * Find and select the required PubSub+ Helm chart variant from the catalog, then click on "Install". * Provide a unique Release Name. It is recommended to change the name that is offered by default. The maximum length of the Release Name should be 28 characters. * If required, provide additional chart configurations. For options, consult the README link at the top of the page. Note that currently the "Form view" offers all the possible fields and the "YAML view" shows only those that have a current configuration value. It may be necessary to refresh the browser to display the latest in "YAML view". @@ -83,7 +85,7 @@ Helm is configured properly if the `helm version` command returns no error. helm repo add openshift-helm-charts https://charts.openshift.io/ ``` -2. Create a new project or switch to your existing project (do not use the `default` project as its loose permissions don't reflect a typical OpenShift environment) +2. Create a new project or switch to your existing project. **Important:** do not use the `default` project as its loose permissions don't reflect a typical OpenShift environment. ```bash oc new-project solace-pubsubplus ``` @@ -101,29 +103,29 @@ Helm is configured properly if the `helm version` command returns no error. 3. Use one of the following Helm chart variants to create a deployment (for configuration options and deletion instructions, refer to the [PubSub+ Software Event Broker Helm Chart](https://github.com/SolaceProducts/pubsubplus-kubernetes-quickstart/tree/master/pubsubplus#configuration) documentation): - - Create a Solace PubSub+ minimum deployment for development purposes using `pubsubplus-openshift-dev`. This variant requires a minimum of 1 CPU and 3.4 GiB of memory to be available to the PubSub+ event broker pod. + - Create a Solace PubSub+ minimum deployment for development purposes using `solace-pubsubplus-openshift-dev`. This variant requires a minimum of 1 CPU and 3.4 GiB of memory to be available to the PubSub+ event broker pod. ```bash # Deploy PubSub+ Standard edition, minimum footprint developer version - helm install my-release openshift-helm-charts/pubsubplus-openshift-dev + helm install my-release openshift-helm-charts/solace-pubsubplus-openshift-dev ``` - - Create a Solace PubSub+ standalone deployment that supports 100 connections using `pubsubplus-openshift`. A minimum of 2 CPUs and 3.4 GiB of memory must be available to the PubSub+ pod. + - Create a Solace PubSub+ standalone deployment that supports 100 connections using `solace-pubsubplus-openshift`. A minimum of 2 CPUs and 3.4 GiB of memory must be available to the PubSub+ pod. ```bash # Deploy PubSub+ Standard edition, standalone - helm install my-release openshift-helm-charts/pubsubplus-openshift + helm install my-release openshift-helm-charts/solace-pubsubplus-openshift ``` - - Create a Solace PubSub+ HA deployment that supports 100 connections using `pubsubplus-openshift-ha`. This deployment requires that at least 2 CPUs and 3.4 GiB of memory are available to *each* of the three event broker pods. + - Create a Solace PubSub+ HA deployment that supports 100 connections using `solace-pubsubplus-openshift-ha`. This deployment requires that at least 2 CPUs and 3.4 GiB of memory are available to *each* of the three event broker pods. ```bash # Deploy PubSub+ Standard edition, HA - helm install openshift-helm-charts/pubsubplus-openshift-ha + helm install my-release openshift-helm-charts/solace-pubsubplus-openshift-ha ``` All of the Helm options above start the deployment and write related information and notes to the console. Broker services are exposed by default through a Load Balancer that is specific to your OpenShift platform. For details, see the `Services access` section of the notes written to the console. - > Note: the `pubsubplus-openshift` Helm charts differ from the general `pubsubplus` charts in that the `securityContext.enabled` Helm parameter value is `false` by default, which is required for OpenShift. + > Note: the `solace-pubsubplus-openshift` Helm charts differ from the general `pubsubplus` charts in that the `securityContext.enabled` Helm parameter value is `false` by default, which is required for OpenShift. 4. Wait for the deployment to complete, following any instructions that are written to the console. You can now [validate the deployment and try the management and messaging services](/docs/PubSubPlusOpenShiftDeployment.md#validating-the-deployment). diff --git a/docs/PubSubPlusOpenShiftDeployment.md b/docs/PubSubPlusOpenShiftDeployment.md index 2bcad91..a039b52 100644 --- a/docs/PubSubPlusOpenShiftDeployment.md +++ b/docs/PubSubPlusOpenShiftDeployment.md @@ -32,14 +32,21 @@ You might also be interested in one of the following: - [Deployment Tools](#deployment-tools) - [Helm Charts](#helm-charts) - [OpenShift Templates](#openshift-templates) -- [Deploying Solace PubSub+ onto OpenShift / AWS](#deploying-solace-pubsub-onto-openshift--aws) - - [Step 1: (Optional / AWS) Deploy a Self-Managed OpenShift Container Platform onto AWS](#step-1-optional--aws-deploy-a-self-managed-openshift-container-platform-onto-aws) - - [Step 2: (Optional / ECR) Use a Private Image Registry](#step-2-optional--ECR-use-a-private-image-registry) +- [Deploying Solace PubSub+ onto OpenShift / AWS](#deploying-solace-pubsub-onto-openshift-aws) + - [Step 1: (Optional / AWS) Deploy a Self-Managed OpenShift Container Platform onto AWS](#step-1-optional-aws-deploy-a-self-managed-openshift-container-platform-onto-aws) + - [Step 2: (Optional / ECR) Use a Private Image Registry](#step-2-optional-ECR-use-a-private-image-registry) - [Step 3, Option 1: Deploy Using Helm](#step-3-option-1-deploy-using-helm) - [Step 3, Option 2: Deploy Using OpenShift Templates](#step-3-option-2-deploy-using-openshift-templates) - [Validating the Deployment](#validating-the-deployment) - [Viewing the Bringup logs](#viewing-the-bringup-logs) - [Gaining Admin and SSH Access to the Event Broker](#gaining-admin-and-ssh-access-to-the-event-broker) +- [Exposing PubSub+ Services](#exposing-pubsub-services) + - [Routes](#routes) + - [HTTP, no TLS](#http-no-tls) + - [HTTPS with TLS terminate at ingress](#https-with-tls-terminate-at-ingress) + - [HTTPS with TLS re-encrypt at ingress](#https-with-tls-re-encrypt-at-ingress) + - [General TCP over TLS with passthrough to broker](#general-tcp-over-tls-with-passthrough-to-broker) +- [Testing PubSub+ Services](#testing-pubsub-services) - [Testing Data Access to the Event Broker](#testing-data-access-to-the-event-broker) - [Deleting a Deployment](#deleting-a-deployment) - [Delete the PubSub+ Deployment](#delete-the-pubsub-deployment) @@ -70,8 +77,9 @@ The Kubernetes `Helm` tool allows great flexibility, allowing the process of eve #### OpenShift Templates -You can directly use the OpenShift templates included in this project, without any additional tools, to deploy the event broker in a limited number of configurations. Follow the instructions for deploying using OpenShift templates in [Step 3, Option 2](#step-3-option-2-deploy-using-openshift-templates), below. +> Deprecation warning: deploying using OpenShift Templates is being phased out and the templates in this quickstart will be no longer maintained. The recommended deployment method is to use Helm. If Helm cannot be used then refer to the [PubSub+ Kubernetes documentation](https://github.com/SolaceProducts/pubsubplus-kubernetes-quickstart/blob/master/docs/PubSubPlusK8SDeployment.md#alternative-deployment-with-generating-templates-for-the-kubernetes-kubectl-tool) to generate deployment manifests. +You can directly use the OpenShift templates included in this project, without any additional tools, to deploy the event broker in a limited number of configurations. Follow the instructions for deploying using OpenShift templates in [Step 3, Option 2](#step-3-option-2-deploy-using-openshift-templates), below. ## Deploying Solace PubSub+ onto OpenShift / AWS @@ -183,9 +191,11 @@ This deployment uses PubSub+ Software Event Broker Helm charts for OpenShift. Yo Consult the [Deployment Considerations](https://github.com/SolaceProducts/pubsubplus-kubernetes-quickstart/blob/master/docs/PubSubPlusK8SDeployment.md#pubsub-software-event-broker-deployment-considerations) section of the general Event Broker in Kubernetes Documentation when planning your deployment. +To use broker TLS ports, you'll need to [configure certificates on the broker](https://github.com/SolaceProducts/pubsubplus-kubernetes-quickstart/blob/master/docs/PubSubPlusK8SDeployment.md#enabling-use-of-tls-to-access-broker-services) or add [OpenShift's service CA bundle to the PubSub+ service](https://docs.openshift.com/container-platform/latest/security/certificates/service-serving-certificate.html#add-service-certificate-apiservice_service-serving-certificate). + PubSub+ Software Event Broker Helm charts for OpenShift differ from the general PubSub+ Helm charts: * The `securityContext.enabled` parameter is set to `false` by default, indicating not to use the provided pod security context but to let OpenShift set it using SecurityContextConstraints (SCC). By default OpenShift will use the "restricted" SCC. -* By default the latest [Red Hat certified image](https://catalog.redhat.com/software/container-stacks/search?q=solace) of PubSub+ Standard Edition is used from `registry.connect.redhat.com`. Use a different image tag if required or [use an image from a different registry](#step-2-optional--ecr-use-a-private-image-registry). If you're using a different image, add the `image.repository=,image.tag=` values (comma-separated) to the `--set` commands below. Also specify a pull secret if required: `image.pullSecretName=` +* By default the latest [Red Hat certified image](https://catalog.redhat.com/software/container-stacks/search?q=solace) of PubSub+ Standard Edition is used from `registry.connect.redhat.com`. Use a different image tag if required or [use an image from a different registry](#step-2-optional--ecr-use-a-private-image-registry). If you're using a different image, add the `image.repository=,image.tag=` values (comma-separated) to the `--set` commands below. Also specify a pull secret if required: `image.pullSecretName=`. Consult the [Red Hat Knowledgebase](https://access.redhat.com/RegistryAuthentication#registry-service-accounts-for-shared-environments-4) if you run into issues with pulling the PubSub+ image. The broker can be [vertically scaled](https://github.com/SolaceProducts/pubsubplus-kubernetes-quickstart/blob/master/docs/PubSubPlusK8SDeployment.md#deployment-scaling ) using the `solace.size` chart parameter. @@ -208,7 +218,7 @@ The broker can be [vertically scaled](https://github.com/SolaceProducts/pubsubpl # Initiate the HA deployment - specify an admin password helm install my-ha-release \ --set solace.redundancy=true,solace.usernameAdminPassword= \ - openshift-helm-charts/pubsubplus-openshift + openshift-helm-charts/solace-pubsubplus-openshift # Check the notes printed on screen # Wait until all pods are running, ready, and the active event broker pod label is "active=true" oc get pods --show-labels -w @@ -222,7 +232,7 @@ The broker can be [vertically scaled](https://github.com/SolaceProducts/pubsubpl helm install my-nonha-release \ --set solace.redundancy=false,solace.usernameAdminPassword= \ --set image.pullSecretName= \ - openshift-helm-charts/pubsubplus-openshift + openshift-helm-charts/solace-pubsubplus-openshift # Check the notes printed on screen # Wait until the event broker pod is running, ready, and the pod label is "active=true" oc get pods --show-labels -w @@ -232,13 +242,13 @@ The broker can be [vertically scaled](https://github.com/SolaceProducts/pubsubpl ```yaml # Create example values file - specify an admin password echo " - solace + solace: redundancy: false, usernameAdminPassword: " > deployment-values.yaml # Use values file helm install my-release \ - -v deployment-values.yaml \ - openshift-helm-charts/pubsubplus-openshift + -f deployment-values.yaml \ + openshift-helm-charts/solace-pubsubplus-openshift ``` ### Step 3, Option 2: Deploy Using OpenShift Templates @@ -467,7 +477,78 @@ Once you have launched the terminal emulator to the event broker pod you can acc See the [Solace Kubernetes Quickstart README](//github.com/SolaceProducts/pubsubplus-kubernetes-quickstart/blob/master/docs/PubSubPlusK8SDeployment.md#gaining-admin-access-to-the-event-broker ) for more details, including admin and SSH access to the individual event brokers. -## Testing Data Access to the Event Broker +## Exposing PubSub+ Services + +The principles of exposing services described in the [PubSub+ in Kubernetes documentation](https://github.com/SolaceProducts/pubsubplus-kubernetes-quickstart/blob/master/docs/PubSubPlusK8SDeployment.md#exposing-the-pubsub-software-event-broker-services) apply: +* LoadBalancer is the default service type and can be used to externally expose all broker services. This is an option for OpenShift as well and will not be further discussed here. +* Ingress and its equivalent, OpenShift Routes, can be used to expose specific services. + +### Routes + + OpenShift has a default production-ready [ingress controller setup based on HAProxy](https://docs.openshift.com/container-platform/latest/networking/understanding-networking.html#nw-ne-openshift-ingress_understanding-networking). Using Routes is the recommended OpenShift-native way to configure Ingress. Refer to the OpenShift documentation for [more information on Ingress and Routes](https://docs.openshift.com/container-platform/latest/networking/understanding-networking.html#nw-ne-openshift-ingress_understanding-networking) and [how to configure Routes](https://docs.openshift.com/container-platform/latest/networking/routes/route-configuration.html). + + The same [table provided for Ingress in the Kubernetes quickstart](https://github.com/SolaceProducts/pubsubplus-kubernetes-quickstart/blob/master/docs/PubSubPlusK8SDeployment.md#using-ingress-to-access-event-broker-services) applies to PubSub+ services vs. route types: HTTP-type broker services can be exposed with TLS edge-terminated or re-encrypt, or without TLS. General TCP services can be exposed using TLS-passthrough to the broker Pods. + + The controller's external (router default) IP address can be determined from looking up the external-IP of the `router-default` service, by running `oc get svc -n openshift-ingress`. OpenShift can automatically assign DNS-resolvable unique host names and TLS-certificates when using Routes (except for TLS-passthrough). It is also possible to assign to the services user-defined host names, for which the user must ensure they DNS-resolve to the router IP, and related TLS-certificates include those hostnames in the CN and/or SAN fields. Note: if a PubSub+ service client requires hostnames provided in the SAN field then user-defined TLS certificates must be used as OpenShift-generated certificates only use CN. + +The followings provide examples for each router type. Replace `` with the name of the service of your deployment. The port name must match the `service.ports` name in the PubSub+ `values.yaml` file. +Additional services can be exposed by additional route for each. + +##### HTTP, no TLS + +This will create an HTTP route to the REST service at path `/`: +```bash +oc expose svc --port tcp-rest \ + --name my-broker-rest-service --path / +# Query the route to get the generated host for accessing the service +oc get route my-broker-rest-service -o template --template='{{.spec.host}}' +``` +External requests shall be targeted to the host at the HTTP port (80) and the specified path. + +##### HTTPS with TLS terminate at ingress + +Terminating TLS at the router is called "edge" in OpenShift. The target port is the backend broker's non-TLS service port. +```bash +oc create route edge my-broker-rest-service-tls-edge \ + --service \ + --port tcp-rest \ + --path / # path is optional and shall not be used for SEMP service +# Query the route to get the generated host for accessing the service +oc get route my-broker-rest-service-tls-edge -o template --template='{{.spec.host}}' +``` +External requests shall be targeted to the host at the TLS port (443) and the specified path. + +> Note: above will use OpenShift's generated TLS certificate which is self-signed by default and includes a wildcard hostname in the CN field. To use user-defined TLS certificates with more control instead, refer to the [OpenShift documentation](https://docs.openshift.com/container-platform/latest/networking/routes/secured-routes.html#nw-ingress-creating-an-edge-route-with-a-custom-certificate_secured-routes) + +##### HTTPS with TLS re-encrypt at ingress + +Re-encrypt requires TLS configured at the backend PubSub+ broker. The target port is now the broker's TLS service port. The broker's CA certificate must be provided in the `--dest-ca-cert` parameter, so the router can trust the broker. +```bash +oc create route reencrypt my-broker-rest-service-tls-reencrypt \ + --service \ + --port tls-rest \ + --dest-ca-cert my-pubsubplus-ca.crt \ + --path / +# Query the route to get the generated host for accessing the service +oc get route my-broker-rest-service-tls-reencrypt -o template --template='{{.spec.host}}' +``` +The TLS certificate note in the previous section is also applicable here. + +##### General TCP over TLS with passthrough to broker + +Passthrough requires TLS-certificate configured on the backend PubSub+ broker that validates all virtual host names for the services exposed, in the CN and/or SAN fields. + +```bash +oc create route passthrough my-broker-smf-service-tls-passthrough \ + --service \ + --port tls-smf \ + --hostname smf.mybroker.com +``` +Here the example PubSub+ SMF messaging service can be accessed at `tcps://smf.mybroker.com:443`. Also, `smf.mybroker.com` must resolve to the router's external IP as discussed above and the broker certificate shall include `*.mybroker.com` in the CN and/or SAN fields. + +The API client must support and use the SNI extension of the TLS handshake to provide the hostname to the OpenShift router for routing the request to the right backend broker. + +## Testing PubSub+ Services A simple option for testing data traffic though the newly created event broker instance is the [SDKPerf tool](https://docs.solace.com/SDKPerf/SDKPerf.htm). Another option to quickly check messaging is [Try Me!](https://docs.solace.com/Solace-PubSub-Manager/PubSub-Manager-Overview.htm#Test-Messages), which is integrated into the [Solace PubSub+ Broker Manager](https://docs.solace.com/Solace-PubSub-Manager/PubSub-Manager-Overview.htm).