Docs Menu

Install and Configure the Atlas Open Service Broker

On this page

Important

Atlas Open Service Broker is deprecated. Use the MongoDB Atlas Operator instead.

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.

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.
  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.

Atlas Open Service Broker is compatible with:

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.

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.

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.

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.

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

1

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
  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

Use the following kubectl command:

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

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
  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

Use the following kubectl command:

kubectl apply -f service-broker.yaml -n <NAMESPACE>
7
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>

After installing the Atlas Open Service Broker, you can:

Give Feedback
MongoDB logo
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.