Welcome to the EnMasse documentation, where you can find information to help you learn about EnMasse and start exploring its features.

From getting started to trying out more advanced installation and configuration, these resources provide what you need to set up and manage EnMasse as a service administrator or a messaging tenant.

1. Overview

EnMasse is an open source project for managed, self-service messaging on Kubernetes and OpenShift. EnMasse can run on your own infrastructure or in the cloud, and simplifies running a messaging infrastructure for your organization.

The service admin can deploy and manage messaging infrastructure, while messaging tenants can request messaging resources, both using both cloud-native APIs and tools.

1.1. Features

  • Built-in authentication and authorization of clients and identity management

  • Runs on Kubernetes and OpenShift: deploy on-premise or in the cloud

  • Different messaging patterns such as request-response, publish-subscribe and events

  • Decouple operation of infrastructure from configuration and use by applications

EnMasse can be used for many purposes, such as moving your messaging infrastructure to the cloud without depending on a specific cloud provider, building a scalable messaging backbone for IoT, or just as a cloud-ready version of a message broker.

EnMasse can provision different types of messaging depending on your use case. A user can request messaging resources by creating an address space.

EnMasse currently supports a standard and a brokered address space type, each with different semantics.

1.1.1. Standard address space

The standard address space type is the default type in EnMasse, and is focused on scaling in the number of connections and the throughput of the system. It supports AMQP and MQTT protocols, with more to come in the future. This address space type is based on other open source projects such as Apache ActiveMQ Artemis and Apache Qpid Dispatch Router and provides elastic scaling of these components. This image illustrates the high-level architecture of the standard address space:

Standard Address Space

1.1.2. Brokered address space

The brokered address space type is the "classic" message broker in the cloud which supports AMQP, CORE, OpenWire, and MQTT protocols. It supports JMS with transactions, message groups, selectors on queues and so on. These features are useful for building complex messaging patterns. This address space is also more lightweight as it features only a single broker and a management console. This image illustrates the high-level architecture of the brokered address space:

Brokered Address Space

2. Getting started

This guide will walk through the process of setting up EnMasse on Kubernetes with clients for sending and receiving messages.

Prerequisite
  • To install EnMasse, you must have Kubernetes installed. You can use minikube if you want to install EnMasse on your laptop.

  • A user on the Kubernetes cluster with cluster-admin permissions is required, in order to set up the required cluster roles and API services.

2.1. Downloading EnMasse

Procedure

2.2. Installing EnMasse using a YAML bundle

The simplest way to install EnMasse is to use the predefined YAML bundles.

Procedure
  1. Create the namespace where you want to deploy EnMasse:

    kubectl create namespace enmasse-infra
    kubectl config set-context $(kubectl config current-context) --namespace=enmasse-infra
  2. Create a certificate to use with the API server. For testing purposes, you can create a self-signed certificate:

    mkdir -p api-server-cert/
    openssl req -new -x509 -batch -nodes -days 11000 -subj "/O=io.enmasse/CN=api-server.enmasse-infra.svc.cluster.local" -out api-server-cert/tls.crt -keyout api-server-cert/tls.key
  3. Create a secret containing the API server certificate:

    kubectl create secret tls api-server-cert --cert=api-server-cert/tls.crt --key=api-server-cert/tls.key
  4. Deploy using the enmasse bundle:

    kubectl apply -f install/bundles/enmasse
  5. (Optional) Install example plans and infrastructure configuration:

    kubectl apply -f install/components/example-plans
  6. (Optional) Install example roles

    kubectl apply -f install/components/example-roles
  7. (Optional) Install the standard authentication service:

    kubectl apply -f install/components/example-authservices/standard-authservice.yaml

2.3. Creating address spaces using the command line

In EnMasse, you create address spaces using standard command-line tools.

Procedure
  1. Create an address space definition:

    apiVersion: enmasse.io/v1beta1
    kind: AddressSpace
    metadata:
      name: myspace
    spec:
      type: standard
      plan: standard-unlimited
  2. Create the address space:

    kubectl create -f standard-address-space.yaml
  3. Check the status of the address space:

    kubectl get addressspace myspace -o jsonpath={.status.isReady}

    The address space is ready for use when the previous command outputs true.

2.4. Creating addresses using the command line

You can create addresses using the command line.

Procedure
  1. Create an address definition:

    apiVersion: enmasse.io/v1beta1
    kind: Address
    metadata:
        name: myspace.myqueue
    spec:
        address: myqueue
        type: queue
        plan: standard-small-queue
    Note
    Prefixing the name with the address space name is required to ensure addresses from different address spaces do not collide.
  2. Create the address:

    kubectl create -f standard-small-queue.yaml
  3. List the addresses:

    kubectl get addresses -o yaml

2.5. Creating users using the command line

In EnMasse users can be created using standard command-line tools.

Prerequisites
Procedure
  1. To correctly base64 encode a password for the user definition file, run the following command:

    echo -n password | base64 #cGFzc3dvcmQ=
    Note
    Be sure to use the -n parameter when running this command. Not specifying that parameter will result in an improperly coded password and cause log-in issues.
  2. Save the user definition to a file:

    apiVersion: user.enmasse.io/v1beta1
    kind: MessagingUser
    metadata:
      name: myspace.user1
    spec:
      username: user1
      authentication:
        type: password
        password: cGFzc3dvcmQ= # Base64 encoded
      authorization:
        - addresses: ["myqueue", "queue1", "queue2", "topic*"]
          operations: ["send", "recv"]
        - addresses: ["anycast1"]
          operations: ["send"]
  3. Create the user and associated user permissions:

    kubectl create -f user-example1.yaml
  4. Confirm that the user was created:

    kubectl get messagingusers

2.6. Sending and receiving messages

Prerequisites
  • Installed Apache Qpid Proton Python bindings.

  • An address space named myspace must be created.

  • An address named myqueue must be created.

  • A user named user1 with password password must be created.

Procedure
  1. Save Python client example to a file:

    from __future__ import print_function, unicode_literals
    import optparse
    from proton import Message
    from proton.handlers import MessagingHandler
    from proton.reactor import Container
    
    class HelloWorld(MessagingHandler):
        def __init__(self, url):
            super(HelloWorld, self).__init__()
            self.url = url
    
        def on_start(self, event):
            event.container.create_receiver(self.url)
            event.container.create_sender(self.url)
    
        def on_sendable(self, event):
            event.sender.send(Message(body="Hello World!"))
            event.sender.close()
    
        def on_message(self, event):
            print("Received: " + event.message.body)
            event.connection.close()
    
    parser = optparse.OptionParser(usage="usage: %prog [options]")
    parser.add_option("-u", "--url", default="amqps://localhost:5672/myqueue",
                      help="url to use for sending and receiving messages")
    opts, args = parser.parse_args()
    
    try:
        Container(HelloWorld(opts.url)).run()
    except KeyboardInterrupt: pass
  2. Retrieve the address space messaging endpoint host name:

    kubectl get addressspace myspace -o 'jsonpath={.status.endpointStatuses[?(@.name=="messaging")].externalHost}'

    Use the output as the host name in the following step.

  3. Run the client:

    python client-example1.py -u amqps://user1:password@messaging.example1.com:443/myqueue

We have seen how to set up EnMasse on Kubernetes, and how to communicate with it using an AMQP client.

3. Service admin guide

The service administrator guide provides resources on how to set up and manage EnMasse, infrastructure configuration, and plans.

3.1. Installing EnMasse

EnMasse can be installed by applying the YAML files using the kubectl command-line tool, or by using the Operator Marketplace.

Prerequisite
  • To install EnMasse, you must have Kubernetes installed. You can use minikube if you want to install EnMasse on your laptop.

  • A user on the Kubernetes cluster with cluster-admin permissions is required, in order to set up the required cluster roles and API services.

3.1.1. Downloading EnMasse

Procedure

3.1.2. Installing EnMasse using a YAML bundle

The simplest way to install EnMasse is to use the predefined YAML bundles.

Procedure
  1. Create the namespace where you want to deploy EnMasse:

    kubectl create namespace enmasse-infra
    kubectl config set-context $(kubectl config current-context) --namespace=enmasse-infra
  2. Create a certificate to use with the API server. For testing purposes, you can create a self-signed certificate:

    mkdir -p api-server-cert/
    openssl req -new -x509 -batch -nodes -days 11000 -subj "/O=io.enmasse/CN=api-server.enmasse-infra.svc.cluster.local" -out api-server-cert/tls.crt -keyout api-server-cert/tls.key
  3. Create a secret containing the API server certificate:

    kubectl create secret tls api-server-cert --cert=api-server-cert/tls.crt --key=api-server-cert/tls.key
  4. Deploy using the enmasse bundle:

    kubectl apply -f install/bundles/enmasse
  5. (Optional) Install example plans and infrastructure configuration:

    kubectl apply -f install/components/example-plans
  6. (Optional) Install example roles

    kubectl apply -f install/components/example-roles
  7. (Optional) Install the standard authentication service:

    kubectl apply -f install/components/example-authservices/standard-authservice.yaml

3.1.3. Installing EnMasse using Operator Marketplace

If the version of EnMasse you want to install is not available in the Operator Hub, you can install a custom OperatorSource for EnMasse following these steps.

Prerequisites
Procedure
  1. Create an OperatorSource:

    cat <<EOF | kubectl apply -f -
    apiVersion: operators.coreos.com/v1
    kind: OperatorSource
    metadata:
      name: enmasse-operators
      namespace: marketplace
    spec:
      type: appregistry
      endpoint: https://quay.io/cnr
      registryNamespace: enmasse
      displayName: "EnMasse Operators"
      publisher: "EnMasse"
    EOF
  2. Create a CatalogSourceConfig to enable the operator on your Kubernetes cluster:

    cat <<EOF | kubectl apply -f -
    apiVersion: operators.coreos.com/v1
    kind: CatalogSourceConfig
    metadata:
      name: installed-enmasse-operators
      namespace: marketplace
    spec:
      csDisplayName: EnMasse Operators
      csPublisher: EnMasse
      packages: enmasse
      targetNamespace: operators
    EOF
  3. Create a Subscription to install the operator and receive updates:

    cat <<EOF | kubectl apply -f -
    apiVersion: operators.coreos.com/v1alpha1
    kind: Subscription
    metadata:
      name: enmasse
      namespace: operators
    spec:
      channel: alpha
      name: enmasse
      source: enmasse-operators
      sourceNamespace: operators
    EOF

3.2. Configuring EnMasse

3.2.1. Service configuration resources and definition

The service operator configures EnMasse by defining resources constituting the "service configuration". This configuration contains instances of the following resource types:

  • AuthenticationService - Describes an authentication service instance used to authenticate messaging clients.

  • AddressSpacePlan - Describes the messaging resources available for address spaces using this plan, such as the available address plans and the amount of router and broker resources that can be used.

  • AddressPlan - Describes the messaging resources consumed by a particular address using this plan, such as what fraction of routers and brokers an address will use and other properties that should be set for multiple addresses.

  • StandardInfraConfig - Describes the router and broker configuration for the standard address space type such as memory limits, storage capacity, affinity, and more.

  • BrokeredInfraConfig - Describes the broker configuration for the brokered address space type such as memory limits, storage capacity, affinity, and more.

When created, these resources define the configuration that is available to the messaging tenants.

The following diagram illustrates the relationship between the different service configuration resources (green) and how they are referenced by the messaging tenant resources (blue).

EnMasse entities

3.2.2. Minimal service configuration

Configuring EnMasse for production takes some time and consideration. The following procedure will get you started with a minimal service configuration. For a more complete example, navigate to the install/components/example-plans folder of the EnMasse distribution. All of the commands must be run in the namespace where EnMasse is installed.

Procedure
  1. Save the example configuration:

    apiVersion: admin.enmasse.io/v1beta1
    kind: StandardInfraConfig
    metadata:
      name: default
    spec: {}
    ---
    apiVersion: admin.enmasse.io/v1beta2
    kind: AddressPlan
    metadata:
      name: standard-small-queue
    spec:
      addressType: queue
      resources:
        router: 0.01
        broker: 0.1
    ---
    apiVersion: admin.enmasse.io/v1beta2
    kind: AddressSpacePlan
    metadata:
      name: standard-small
    spec:
      addressSpaceType: standard
      infraConfigRef: default
      addressPlans:
      - standard-small-queue
      resourceLimits:
        router: 2.0
        broker: 3.0
        aggregate: 4.0
    ---
    apiVersion: admin.enmasse.io/v1beta1
    kind: AuthenticationService
    metadata:
      name: none-authservice
    spec:
      type: none
  2. Apply the example configuration:

    kubectl apply -f service-config.yaml

3.2.3. Address space plans

Address space plans are used to configure quotas and control the resources consumed by address spaces. Address space plans are configured by the EnMasse service operator and are selected by the messaging tenant when creating an address space.

EnMasse includes a default set of plans that are sufficient for most use cases.

Plans are configured as custom resources. The following example shows a plan for the standard address space:

apiVersion: admin.enmasse.io/v1beta2
kind: AddressSpacePlan
metadata:
  name: restrictive-plan
  labels:
    app: enmasse
spec:
  displayName: Restrictive Plan
  displayOrder: 0
  infraConfigRef: default (1)
  shortDescription: A plan with restrictive quotas
  longDescription: A plan with restrictive quotas for the standard address space
  addressSpaceType: standard (2)
  addressPlans: (3)
  - small-queue
  - small-anycast
  resourceLimits: (4)
    router: 2.0
    broker: 2.0
    aggregate: 2.0
  1. A reference to the StandardInfraConfig (for the standard address space type) or the BrokeredInfraConfig (for the brokered address space type) describing the infrastructure deployed for address spaces using this plan.

  2. The address space type this plan applies to, either standard or brokered.

  3. A list of address plans available to address spaces using this plan.

  4. The maximum number of routers (router) and brokers (broker) for address spaces using this plan. For the brokered address space type, only the broker field is required.

The other fields are used by the EnMasse Console UI. Note the field spec.infraConfigRef, which points to an infrastructure configuration that must exist when an address space using this plan is created. For more information about infrastructure configurations, see Infrastructure configuration.

3.2.4. Creating address space plans

Procedure
  1. Create an address space plan definition:

    apiVersion: admin.enmasse.io/v1beta2
    kind: AddressSpacePlan
    metadata:
      name: restrictive-plan
      labels:
        app: enmasse
    spec:
      displayName: Restrictive Plan
      displayOrder: 0
      infraConfigRef: default
      shortDescription: A plan with restrictive quotas
      longDescription: A plan with restrictive quotas for the standard address space
      addressSpaceType: standard
      addressPlans:
      - small-queue
      - small-anycast
      resourceLimits:
        router: 2.0
        broker: 2.0
        aggregate: 2.0
  2. Create the address space plan:

    kubectl create -f restrictive-plan.yaml
  3. Verify that schema has been updated and contains the plan:

    kubectl get addressspaceschema standard -o yaml

3.2.5. Address plans

Address plans specify the expected resource usage of a given address. The sum of the resource usage for all resource types determines the amount of infrastructure provisioned for an address space. A single router and broker pod has a maximum usage of one. If a new address requires additional resources and the resource consumption is within the address space plan limits, a new pod will be created automatically to handle the increased load.

Address plans are configured by the EnMasse service operator and are selected when creating an address.

EnMasse includes a default set of address plans that are sufficient for most use cases.

In the Address space plans section, the address space plan references two address plans: small-queue and small-anycast. These address plans are stored as custom resources and are defined as follows:

apiVersion: admin.enmasse.io/v1beta2
kind: AddressPlan
metadata:
  name: small-queue
  labels:
    app: enmasse
spec:
  displayName: Small queue plan
  displayOrder: 0
  shortDescription: A plan for small queues
  longDescription: A plan for small queues that consume little resources
  addressType: queue (1)
  resources: (2)
    router: 0.2
    broker: 0.3
  partitions: 1 (3)
  1. The address type this plan applies to.

  2. The resources consumed by addresses using this plan. The router field is optional for address plans referenced by a brokered address space plan.

  3. The number of partitions that should be created for queues using this plan. Only available in the standard address space.

The other fields are used by the EnMasse Console UI.

A single router can support five instances of addresses and broker can support three instances of addresses with this plan. If the number of addresses with this plan increases to four, another broker is created. If it increases further to six, another router is created as well.

In the standard address space, address plans for the queue address type may contain a field partitions, which allows a queue to be sharded accross multiple brokers for HA and improved performance. Specifying an amount of broker resource above 1 will automatically cause a queue to be partitioned.

Note
A sharded queue no longer guarantees message ordering.

Although the example address space plan in Address space plans allows two routers and two brokers to be deployed, it only allows two pods to be deployed in total. This means that the address space is restricted to three addresses with the small-queue plan.

The small-anycast plan does not consume any broker resources, and can provision two routers at the expense of not being able to create any brokers:

apiVersion: admin.enmasse.io/v1beta2
kind: AddressPlan
metadata:
  name: small-anycast
  labels:
    app: enmasse
spec:
  addressType: anycast
  resources:
    router: 0.2

With this plan, up to 10 addresses can be created.

3.2.6. Creating address plans

Procedure
  1. Create an address plan definition:

    apiVersion: admin.enmasse.io/v1beta2
    kind: AddressPlan
    metadata:
      name: small-anycast
      labels:
        app: enmasse
    spec:
      addressType: anycast
      resources:
        router: 0.2
  2. Create the address plan:

    kubectl create -f small-anycast-plan.yaml
  3. Verify that schema has been updated and contains the plan:

    kubectl get addressspaceschema standard -o yaml

3.2.7. Infrastructure configuration

EnMasse creates infrastructure components such as routers, brokers, and consoles. These components can be configured while the system is running, and EnMasse automatically updates the components with the new settings. The EnMasse service operator can edit the EnMasse default infrastructure configuration or create new configurations.

Infrastructure configurations can be referred to from one or more address space plans. For more information about address space plans, see Address space plans.

Infrastructure configuration can be managed for both brokered and standard infrastructure using BrokeredInfraConfig and StandardInfraConfig resources.

Brokered infrastructure configuration

BrokeredInfraConfig resources are used to configure infrastructure deployed by brokered address spaces. The brokered infrastructure configuration is referenced by address space plans in their spec.infraConfigRef field. For more information, see Address space plans.

For detailed information about the available brokered infrastructure configuration fields, see the Brokered infrastructure configuration fields table.

apiVersion: admin.enmasse.io/v1beta1
kind: BrokeredInfraConfig
metadata:
  name: brokered-infra-config-example
spec:
  version: "0.29-SNAPSHOT"
  admin:
    resources:
      memory: 256Mi
    podTemplate:
      metadata:
        labels:
          key: value
  broker:
    resources:
      memory: 2Gi
      storage: 100Gi
    addressFullPolicy: PAGE
    podTemplate:
      spec:
        priorityClassName: messaging

The version field specifies the EnMasse version used. When upgrading, EnMasse uses this field to determine whether to upgrade the infrastructure to the requested version. If omitted, the version will be assumed to be the same as the controllers reading the config.

The admin object specifies the settings you can configure for the admin components.

The broker object specifies the settings you can configure for the broker components. Changing the .broker.resources.storage setting does not configure the existing broker storage size.

For both admin and broker you can configure podTemplate settings like metadata.labels, spec.priorityClassName, spec.tolerations and spec.affinity.

Standard infrastructure configuration

StandardInfraConfig resources are used to configure infrastructure deployed by standard address spaces. The standard infrastructure configuration is referenced by address space plans in their spec.infraConfigRef field. For more information, see Address space plans.

For detailed information about the available standard infrastructure configuration fields, see the Standard infrastructure configuration fields table.

apiVersion: admin.enmasse.io/v1beta1
kind: StandardInfraConfig
metadata:
  name: myconfig
spec:
  version: "0.29-SNAPSHOT"
  admin:
    resources:
      memory: 256Mi
  broker:
    resources:
      memory: 2Gi
      storage: 100Gi
    addressFullPolicy: PAGE
  router:
    resources:
      memory: 256Mi
    linkCapcity: 1000
    minReplicas: 1
    policy:
      maxConnections: 1000
      maxConnectionsPerHost: 1
      maxConnectionsPerUser: 10
      maxSessionsPerConnection: 10
      maxSendersPerConnection: 5
      maxReceiversPerConnection: 5
    podTemplate:
      spec:
        affinity:
          nodeAffinity:
            preferredDuringSchedulingIgnoredDuringExecution:
            - weight: 1
              preference:
              matchExpressions:
              - key: e2e-az-EastWest
                operator: In
                values:
                - e2e-az-East
                - e2e-az-West

The version field specifies the EnMasse version used. When upgrading, EnMasse uses this field to determine whether to upgrade the infrastructure to the requested version. If omitted, the version will be assumed to be the same as the controllers reading the config.

The admin object specifies the settings you can configure for the admin components.

The broker object specifies the settings you can configure for the broker components. Changing the .broker.resources.storage setting does not configure the existing broker storage size.

The router object specifies the settings you can configure for the router components.

For admin, broker and router you can configure podTemplate settings like metadata.labels, spec.priorityClassName, spec.tolerations and spec.affinity.

3.2.8. Applying infrastructure configuration

You can edit existing configurations or create new ones.

Prerequisites
Procedure
  1. Create infrastructure configuration:

    apiVersion: admin.enmasse.io/v1beta1
    kind: StandardInfraConfig
    metadata:
      name: myconfig
    spec:
      version: "0.29-SNAPSHOT"
      admin:
        resources:
          memory: 256Mi
      broker:
        resources:
          memory: 2Gi
          storage: 100Gi
        addressFullPolicy: PAGE
      router:
        resources:
          memory: 256Mi
        linkCapcity: 1000
        minReplicas: 1
  2. Apply the configuration changes:

    kubectl apply -f standard-infra-config-example.yaml
  3. Monitor the pods while they are restarted:

    kubectl get pods -w

    The configuration changes will be applied within a couple of minutes.

3.2.9. Authentication services

Authentication services are used to configure the authentication and authorization endpoints available to messaging clients. The authentication services are configured by the EnMasse service operator, and are specified when creating an address space.

An authentication service has a type, which can either be none, standard, or external. The none authentication service type allows all clients to send and receive messages to any address.

The standard authentication service type uses a Keycloak instance to store user credentials and access policies. This authentication service also allows managing users using the MessagingUser custom resource.

The external authentication service allows configuring an external provider of authentication and authorization policies through an AMQP SASL handshake. This can be used to implement a bridge for your existing identity management system.

Authentication services are configured as custom resources. The following example shows an authentication service of type standard:

apiVersion: admin.enmasse.io/v1beta1
kind: AuthenticationService
metadata:
  name: standard
spec:
  type: standard (1)
  standard:
    credentialsSecret: (2)
      name: my-admin-credentials
    certificateSecret (3)
      name: my-authservice-certificate
    resources: (4)
      requests:
        memory: 2Gi
      limits:
        memory: 2Gi
    storage: (5)
      type: persistent-claim
      size: 5Gi
    datasource: (6)
      type: postgresql
      host: example.com
      port: 5432
      database: authdb
  1. The type can be specified as none, standard, or external.

  2. (Optional) The secret must contain the admin.username field for the user and the admin.password field for the password of the Keycloak admin user. If not specified, a random password will be generated and stored in a secret.

  3. (Optional on OpenShift) A custom certificate can be specified. On OpenShift, a certificate is automatically created if not specified.

  4. (Optional) Resource limits for the Keycloak instance can be specified.

  5. (Optional) The storage type can be specified as ephemeral or persistent-claim. For persistent-claim, you should also configure the size of the claim. The default type is ephemeral.

  6. (Optional) Specifies the data source to be used by Keycloak. The default option is the embedded h2 data source. For production usage, the postgresql data source is recommended.

An external authentication service can be configured using the following example:

apiVersion: admin.enmasse.io/v1beta1
kind: AuthenticationService
metadata:
  name: my-im-system
spec:
  type: external
  realm: myrealm (1)
  external:
    host: example.com (2)
    port: 5671 (3)
    caCertSecret: (4)
      name: my-ca-cert
  1. (Optional) The realm is passed in the authentication request. If not specified, an identifier in the form of namespace-addressspace is used as the realm.

  2. The host name of the external authentication service.

  3. The port of the external authentication service.

  4. (Optional) The CA certificate to trust when connecting to the authentication service.

The external authentication service must implement the API described in External authentication service API.

3.2.10. Deploying the standard authentication service

Procedure
  1. Create an AuthenticationService definition:

    apiVersion: admin.enmasse.io/v1beta1
    kind: AuthenticationService
    metadata:
      name: standard-authservice
    spec:
      type: standard
  2. Deploy the authentication service:

    kubectl create -f standard-authservice.yaml

3.2.11. Deploying the none authentication service

Procedure
  1. Create an AuthenticationService definition:

    apiVersion: admin.enmasse.io/v1beta1
    kind: AuthenticationService
    metadata:
      name: none-authservice
    spec:
      type: none
  2. Deploy the authentication service:

    kubectl create -f none-authservice.yaml

3.2.12. External authentication service API

An external authentication service must implement an AMQP SASL handshake, read the connection properties of the client, and respond with the expected connection properties containing the authentication and authorization information. The authentication service is queried by the address space components such as the router and broker, whenever a new connection is established to the messaging endpoints.

Authentication

The requested identity of the client can be read from the SASL handshake username. The implementation can then authenticate the user.

The authenticated identity will be returned in the authenticated-identity map with the following key/values. While this example uses JSON, it should be set as an AMQP map on the connection property.

{
    "authenticated-identity": {
        "sub": "myid",
        "preferred_username": "myuser"
    }
}
Authorization

Authorization is a capability that can be requested by the client using the ADDRESS-AUTHZ connection capability. If this is set on the connection, the server responds with this capability in the offered capabilities, and add the authorization information to the connection properties.

The authorization information is stored within a map that correlates the address to a list of operations allowed on that address. The following connection property information contains the policies for the addresses myqueue and mytopic:

{
    "address-authz": {
        "myqueue": [
          "send",
          "recv"
        ],
        "mytopic": [
          "send"
        ]
    }
}

The allowed operations are:

  • send - User can send to the address.

  • recv - User can receive from the address.

3.2.13. EnMasse example roles

EnMasse provides the following example roles that you can use directly or use as models to create your own roles.

For more information about service administrator resources, see the EnMasse service administrator resources table. For more information about messaging tenant resources, see the EnMasse messaging tenant resources table.

Table 1. EnMasse example roles table
Role Description

enmasse.io:tenant-view

Specifies get and list permissions for addresses, addressspaces, addressspaceschemas, and messagingusers

enmasse.io:tenant-edit

Specifies create, get, update, delete, list, watch, and patch permissions for addresses, addressspaces, and messagingusers; get and list permissions for addressspaceschemas

service-admin cluster role

Specifies create, get, update, delete, list, watch, and patch permissions for addressplans, addressspaceplans, brokeredinfraconfigs, and standardinfraconfigs

3.3. Upgrading EnMasse

EnMasse supports upgrades between minor versions using cloud native tools and the same mechanism used to apply configuration changes. When upgrading, the updated infrastructure configuration of the new version will trigger the upgrade to start.

Upgrading EnMasse is done by applying the YAML files for the new version.

3.3.1. Upgrading EnMasse using a YAML bundle

Prerequisites
Procedure
  1. Select the namespace where EnMasse is installed:

    kubectl config set-context $(kubectl config current-context) --namespace=enmasse-infra
  2. Apply the new release bundle:

    kubectl apply -f install/bundles/enmasse
  3. Monitor pods while they are restarted:

    kubectl get pods -w

    The upgrade should cause all pods to be restarted within a couple of minutes.

3.4. Uninstalling EnMasse

Procedure
  1. Delete "cluster level" resources:

    kubectl delete clusterrolebindings -l app=enmasse
    kubectl delete crd -l app=enmasse
    kubectl delete clusterroles -l app=enmasse
    kubectl delete apiservices -l app=enmasse
  2. Delete the namespace where EnMasse is deployed:

    kubectl delete namespace enmasse-infra

3.5. Monitoring EnMasse

You can monitor EnMasse by deploying built-in monitoring tools or using your pre-existing monitoring infrastructure by deploying the required service monitors and Prometheus rules.

3.5.1. (Optional) Deploying the Application Monitoring Operator

To monitor EnMasse, an operator that acts on the monitoring Custom Resource Definitions must be deployed. You may skip this step if you have such an operator installed on your Kubernetes cluster.