Navigation

    Install and Configure the Atlas Open Service Broker

    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