Chapter 3. Preparing for your AMQ Streams deployment

This section shows how you prepare for a AMQ Streams deployment, describing:

Note

To run the commands in this guide, your cluster user must have the rights to manage role-based access control (RBAC) and CRDs.

3.1. Deployment prerequisites

To deploy AMQ Streams, make sure:

  • An OpenShift 4.6 and later cluster is available

    AMQ Streams is based on AMQ Streams Strimzi 0.22.x.

  • The oc command-line tool is installed and configured to connect to the running cluster.
Note

AMQ Streams supports some features that are specific to OpenShift, where such integration benefits OpenShift users and there is no equivalent implementation using standard OpenShift.

3.2. Downloading AMQ Streams release artifacts

To install AMQ Streams, download and extract the release artifacts from the amq-streams-<version>-ocp-install-examples.zip file from the AMQ Streams download site.

AMQ Streams release artifacts include sample YAML files to help you deploy the components of AMQ Streams to OpenShift, perform common operations, and configure your Kafka cluster.

Use oc to deploy the Cluster Operator from the install/cluster-operator folder of the downloaded ZIP file. For more information about deploying and configuring the Cluster Operator, see Section 5.1.1, “Deploying the Cluster Operator”.

In addition, if you want to use standalone installations of the Topic and User Operators with a Kafka cluster that is not managed by the AMQ Streams Cluster Operator, you can deploy them from the install/topic-operator and install/user-operator folders.

Note

Additionally, AMQ Streams container images are available through the Red Hat Ecosystem Catalog. However, we recommend that you use the YAML files provided to deploy AMQ Streams.

3.3. Authenticating with the container registry for Kafka Connect S2I

You need to configure authentication with the Red Hat container registry (registry.redhat.io) before creating a container image using OpenShift builds and Source-to-Image (S2I).

The container registry is used to store AMQ Streams container images on the Red Hat Ecosystem Catalog. The Catalog contains a Kafka Connect builder image with S2I support. The OpenShift build pulls this builder image, together with your source code and binaries, and uses it to build the new container image.

Note

Authentication with the Red Hat container registry is only required if using Kafka Connect S2I. It is not required for the other AMQ Streams components.

Prerequisites

Procedure

  1. If needed, log in to your OpenShift cluster as an administrator: 

    oc login --user system:admin --token=my-token --server=https://my-cluster.example.com:6443

  2. Open the project that will contain the Kafka Connect S2I cluster: 

    oc project CLUSTER-NAME
    Note

    You might have already deployed the Kafka Connect S2I cluster.

  3. Create a docker-registry secret using your Red Hat Customer Portal account, replacing PULL-SECRET-NAME with the secret name to create: 

    oc create secret docker-registry PULL-SECRET-NAME \
 --docker-server=registry.redhat.io \
 --docker-username=CUSTOMER-PORTAL-USERNAME \
 --docker-password=CUSTOMER-PORTAL-PASSWORD \
 --docker-email=EMAIL-ADDRESS

    You should see the following output: 

    secret/PULL-SECRET-NAME created
    Important

    You must create this docker-registry secret in every OpenShift project that will authenticate to registry.redhat.io.

  4. Link the secret to your service account to use the secret for pulling images. The service account name must match the name that the OpenShift pod uses. 

    oc secrets link SERVICE-ACCOUNT-NAME PULL-SECRET-NAME --for=pull

    For example, using the default service account and a secret named my-secret: 

    oc secrets link default my-secret --for=pull

  5. Link the secret to the builder service account to use the secret for pushing and pulling build images: 

    oc secrets link builder PULL-SECRET-NAME
    Note

    If you do not want to use your Red Hat username and password to create the pull secret, you can create an authentication token using a registry service account.

Additional resources

3.4. Pushing container images to your own registry

Container images for AMQ Streams are available in the Red Hat Ecosystem Catalog. The installation YAML files provided by AMQ Streams will pull the images directly from the Red Hat Ecosystem Catalog.

If you do not have access to the Red Hat Ecosystem Catalog or want to use your own container repository:

  1. Pull all container images listed here
  2. Push them into your own registry
  3. Update the image names in the installation YAML files
Note

Each Kafka version supported for the release has a separate image.

Container imageNamespace/RepositoryDescription

Kafka

  • registry.redhat.io/amq7/amq-streams-kafka-27-rhel7:1.7.0
  • registry.redhat.io/amq7/amq-streams-kafka-26-rhel7:1.7.0

AMQ Streams image for running Kafka, including:

  • Kafka Broker
  • Kafka Connect / S2I
  • Kafka Mirror Maker
  • ZooKeeper
  • TLS Sidecars

Operator

  • registry.redhat.io/amq7/amq-streams-rhel7-operator:1.7.0

AMQ Streams image for running the operators:

  • Cluster Operator
  • Topic Operator
  • User Operator
  • Kafka Initializer

Kafka Bridge

  • registry.redhat.io/amq7/amq-streams-bridge-rhel7:1.7.0

AMQ Streams image for running the AMQ Streams Kafka Bridge

3.5. Designating AMQ Streams administrators

AMQ Streams provides custom resources for configuration of your deployment. By default, permission to view, create, edit, and delete these resources is limited to OpenShift cluster administrators. AMQ Streams provides two cluster roles that you can use to assign these rights to other users:

  • strimzi-view allows users to view and list AMQ Streams resources.
  • strimzi-admin allows users to also create, edit or delete AMQ Streams resources.

When you install these roles, they will automatically aggregate (add) these rights to the default OpenShift cluster roles. strimzi-view aggregates to the view role, and strimzi-admin aggregates to the edit and admin roles. Because of the aggregation, you might not need to assign these roles to users who already have similar rights.

The following procedure shows how to assign a strimzi-admin role that allows non-cluster administrators to manage AMQ Streams resources.

A system administrator can designate AMQ Streams administrators after the Cluster Operator is deployed.

Prerequisites

Procedure

  1. Create the strimzi-view and strimzi-admin cluster roles in OpenShift. 

    oc create -f install/strimzi-admin

  2. If needed, assign the roles that provide access rights to users that require them. 

    oc create clusterrolebinding strimzi-admin --clusterrole=strimzi-admin --user=user1 --user=user2