Navigation

Install and Configure the Atlas Open Service Broker

Note

This tutorial presumes some knowledge of Kubernetes, but does link to relevant Kubernetes documentation where possible. If you are unfamiliar with Kubernetes, review the Kubernetes documentation first.

Prerequisites

Atlas Prerequisites

To install the Atlas Open Service Broker, you must:

  1. Set up a payment method for Atlas billing.
  2. Create a project in which your clusters will be deployed.
  3. Have or generate a Programmatic API Key.
    1. Grant this new Programmatic API Key the Project Owner role.
    2. Add the IP or CIDR block of any hosts that serve the Atlas Open Service Broker to the API Whitelist.

Kubernetes Prerequisites

  1. Have a Kubernetes solution available to use.

    If you need a Kubernetes solution, see the Kubernetes documentation on picking the right solution.

  2. Install the Kubernetes Service Catalog.

  3. Install the Kubernetes Service Catalog CLI.

Considerations

Kubernetes Compatibility

Atlas Open Service Broker is compatible with:

Atlas Open Service Broker Scope

When you create an instance of the Atlas Open Service Broker, you register it with Kubernetes as either a cluster-scoped clusterServiceBroker or a namespace-scoped serviceBroker.

For more information on the use cases for cluster-scoped and namespace-scoped brokers, see the Kubernetes Service Catalog documentation.

ClusterServiceBroker

An Atlas Open Service Broker instance that is registered as a ClusterServiceBroker is available to the entire Kubernetes cluster. When you deploy a Atlas replica set or sharded cluster, you must use the associated clusterServiceClass and clusterServicePlan resources.

ServiceBroker

An Atlas Open Service Broker instance that is registered as a ServiceBroker is available to only a single namespace within the Kubernetes cluster. When you deploy a Atlas replica set or sharded cluster, you must use the serviceClass and servicePlan resources scoped to the same namespace.

Multiple Atlas Open Service Broker Instances

When you create an instance of the Atlas Open Service Broker, you can deploy:

  • A single Atlas Open Service Broker instance scoped to the entire Kubernetes cluster or

  • Multiple Atlas Open Service Broker instances scoped to their own namespaces within the Kubernetes cluster

    Important

    If you choose to deploy multiple Atlas Open Service Broker instances, deploy only one instance per namespace. Multiple Atlas Open Service Broker instances cannot coordinate with one another within the same namespace.

Install the Atlas Open Service Broker

To deploy the Atlas Open Service Broker in Kubernetes, use the following procedure.

1

Create a namespace for your Kubernetes deployment.

To simplify your installation, consider creating a namespace labeled atlas using the following kubectl command:

kubectl create namespace atlas

If you do not want to use the atlas namespace, you can label your namespace anything you like:

kubectl create namespace <NAMESPACE_NAME>
2

Create the Deployment and Service resource definition.

  1. Copy the following resource definition example.

    This is a YAML file that you can modify to meet your desired configuration. It includes both the Deployment and Service specifications.

    Note

    The example uses atlas-service-broker as the deployment name, service name, and pod label. You can update these fields with other values as long as you are consistent across resources.

    ---
    # Deployment to run the service broker.
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: atlas-service-broker
      labels:
        app: atlas-service-broker
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: atlas-service-broker
      template:
        metadata:
          labels:
            app: atlas-service-broker
        spec:
          containers:
            - name: atlas-service-broker
              image: quay.io/mongodb/mongodb-atlas-service-broker:latest
              ports:
                - containerPort: 4000
              env:
                - name: BROKER_HOST
                  value: "0.0.0.0"
    
    ---
    # Service to expose the service broker inside the cluster.
    apiVersion: v1
    kind: Service
    metadata:
      name: atlas-service-broker
      labels:
        app: atlas-service-broker
    spec:
      selector:
        # Will match pods deployed by the "atlas-service-broker" deployment.
        app: atlas-service-broker
      ports:
        - protocol: TCP
          port: 80
          targetPort: 4000
    
  2. Open your preferred text editor and paste the resource definition into a new text file.

  3. Confirm or edit the container port which the Atlas Open Service Broker server listens on.

    Resource Environment Variable Description Default
    Deployment
    spec.template.spec
    .containers.ports.containerPort

    The port which the Atlas Open Service Broker server listens on.

    Must match the value of targetPort in the Service resource.

    4000
    Service
    spec.ports.targetPort

    The port which the Atlas Open Service Broker server listens on.

    Must match the value of containerPort in the Deployment resource.

    4000
  4. Save the file as deployment-and-service.yaml.

3

Install the Atlas Open Service Broker.

Use the following kubectl command:

kubectl apply -f deployment-and-service.yaml -n <NAMESPACE>
4

Create a Kubernetes secret.

For the Atlas Open Service Broker to create or update objects in your Atlas Project, you need to store your Programmatic API Key and Project ID as a Kubernetes secret.

Multiple secrets can exist in the same namespace.

To create your Kubernetes secret:

  1. Make sure you have the following:

    • Public and Private Keys for your desired Atlas Programmatic API Key.

      If you do not have a Programmatic API Key, generate a new Programmatic API Key.

    • The Project ID for your Atlas project.

  2. Copy the following resource definition example.

    This is a YAML that you can modify to meet your desired configuration.

    apiVersion: v1
    kind: Secret
    metadata:
      name: <SECRET_NAME>
    type: Opaque
    stringData:
      username: <PUBLIC_KEY>@<PROJECT_ID>
      password: <PRIVATE_KEY>
    
  3. Edit the following fields:

    Field Name Description
    stringData.username Your Atlas Public Key followed by @ and your Project ID.
    stringData.password Your Atlas Private Key.

    The username and password are used for Basic authentication against the Atlas Open Service Broker.

    Example

    apiVersion: v1
    kind: Secret
    metadata:
      name: atlas-service-broker-auth
    type: Opaque
    stringData:
      username: ABCAXNVY@5d49a272ce4bd97b2e1234abc
      password: 123e8d75-cxfb-x012-bx5c-abc4356e3xyz
    
  4. Save the file as secret.yaml.

  5. Invoke the following Kubernetes command to create your secret:

    kubectl apply -f secret.yaml -n <NAMESPACE>
    

    The -n flag limits the namespace to which this secret applies.

  6. Invoke the following Kubernetes command to verify your secret:

    kubectl describe secrets/<SECRET_NAME> -n <NAMESPACE>
    

    This command returns a secret description in the shell:

    Name:         <SECRET_NAME>
    Namespace:    <NAMESPACE>
    Labels:       <none>
    Annotations:
    Type:         Opaque
    
    Data
    ====
    password:  36 bytes
    username:  36 bytes
    
5

Create a service broker resource definition.

  1. Copy the following resource definition example.

    This is a YAML file that you can modify to meet your desired configuration.

    apiVersion: servicecatalog.k8s.io/v1beta1
    kind: <SERVICE_BROKER_SCOPE>
    metadata:
      name: atlas-service-broker
    spec:
      url: http://<SERVICE_NAME>.<NAMESPACE>
      authInfo:
        basic:
          secretRef:
            name: <SECRET_NAME>
            namespace: <NAMESPACE>
    
  2. Edit the following fields:

    Field Name Description
    kind

    This value determines whether the Atlas Open Service Broker is available to the entire Kubernetes cluster or to only a single namespace within the Kubernetes cluster. For more information on service broker resources, see the Service Catalog documentation.

    Possible values are:

    ServiceBroker Deploys the Atlas Open Service Broker scoped to only a single namespace. Any Atlas clusters must be provisioned in the same namespace as the Atlas Open Service Broker.
    ClusterServiceBroker Deploys the Atlas Open Service Broker scoped to an entire Kubernetes cluster. Atlas clusters can be provisioned in any namespace.
    spec.url

    The URL of the broker in the format http://<SERVICE_NAME>.<NAMESPACE>.

    <SERVICE_NAME> is the value of metadata.name in your Service resource.

    Example

    http://atlas-service-broker.atlas
    
    spec.authInfo
    .basic.secretRef.name
    The name of the Kubernetes secret that you created in the previous step.
    spec.authInfo
    .basic.secretRef.namespace
    Your namespace.
  3. Save the file as service-broker.yaml.

6

Register the Atlas Open Service Broker with the Service Catalog

Use the following kubectl command:

kubectl apply -f service-broker.yaml -n <NAMESPACE>
7

Check the status of the Atlas Open Service Broker with the Service Catalog CLI.

svcat get brokers -n <NAMESPACE>

The command returns the status of the broker. If the status of the broker does not appear, wait a few moments and invoke the command again.

Example

The following example shows the status of a broker that was defined as a ClusterServiceBroker. Because this broker is deployed at the cluster level, there is no namespace.

           NAME          NAMESPACE                 URL                   STATUS
+----------------------+-----------+-----------------------------------+--------+
  atlas-service-broker               http://atlas-service-broker.atlas     Ready

If your broker has a status other than Ready, pass the metadata.name from service-broker.yaml into the following command to view a detailed error message:

svcat describe broker <METADATA.NAME> -n <NAMESPACE>