}}

About provisioning Marathon-LB with a service account

Whether you can or must provision Marathon-LB with a service account varies by security mode.

  • disabled: optional
  • permissive: optional
  • strict: required

To increase the security of your cluster and conform to the principle of least privilege, we recommend provisioning Marathon-LB with a service account in permissive mode. Otherwise, Marathon-LB will use the default dcos_anonymous account to authenticate and the dcos_anonymous account has the superuser permission.

In addition, if you plan to upgrade to strict mode, provisioning Marathon-LB with a service account in disabled and permissive modes will make the upgrade easier.

If you set up multiple Marathon-LB instances that interact with the same Marathon instance, you can use the same service account for each Marathon-LB instance.

This topic describes how to provision a Marathon-LB instance that interacts with the native Marathon instance.

To set up a service account for Marathon-LB, complete the following steps.

  1. Create a key pair.
  2. Create a service account.
  3. Create a service account secret.
  4. Provision the service account with the necessary permissions.
  5. Create a config.json file.

Requirement: In strict mode, the name of the service account must match the name that the service uses as its principal. By default, Marathon-LB uses mlb-principal as the name of its principal. That’s the value that we use in the following procedures. Should you modify the default, you must change mlb-principal throughout to match.

Note: We will use mlb-secret as the name of the secret, mlb-private-key.pem as the name of the file containing the private key, and mlb-public-key.pem as the name of the file containing the public key. We recommend sticking to these names as it will make it easier to copy and paste the commands. If you do decide to change the names, make sure to modify the commands before issuing them.

Important: We store the secret in the marathon-lb path. This protects it from other services, so we do not recommend changing this.

Create a key pair

First, you’ll need to generate a 2048-bit RSA public-private key pair. While you can use any tool to accomplish this, the Enterprise DC/OS CLI is the most convenient because it returns the keys in the format needed by DC/OS.

Prerequisite: You must have the DC/OS CLI installed and the Enterprise DC/OS CLI 0.4.14 or later installed.

  1. Use the following command to create a public-private key pair and save each value into a separate file within the current directory.
    dcos security org service-accounts keypair mlb-private-key.pem mlb-public-key.pem
    
  2. Type ls to view the two new files created by the command. You may also want to open the files themselves and verify their contents.

  3. Continue to the next section.

Create a service account

About creating a service account

Next, you must create a service account. This section describes how to use either the Enterprise DC/OS CLI or the web interface to accomplish this.

Using the Enterprise DC/OS CLI

Prerequisite: You must have the DC/OS CLI installed, the Enterprise DC/OS CLI 0.4.14 or later installed, and be logged in as a superuser via dcos auth login.

  1. Use the following command to create a new service account called mlb-principal containing the public key you just generated.
    dcos security org service-accounts create -p mlb-public-key.pem -d "Marathon-LB service account" mlb-principal
    
  2. Verify your new service account using the following command.
    dcos security org service-accounts show mlb-principal
    
  3. Continue to Create a service account secret.

Using the web interface

  1. In the DC/OS web interface, navigate to the System -> Organization -> Service Accounts tab.

  2. Click New Service Account.

  3. Enter a description, the service account ID, and the public key associated with the account. Simply copy the contents of the relevant public key file into the Public Key field.

  4. Continue to Create a service account secret.

Create a service account secret

About creating a service account secret

Next, you need to create a secret associated with the service account that contains the private key. This section describes how to use either the Enterprise DC/OS CLI or the web interface to accomplish this.

Using the Enterprise DC/OS CLI

Prerequisite: You must have the DC/OS CLI installed, the Enterprise DC/OS CLI 0.4.14 or later installed, and be logged in as a superuser via dcos auth login.

  1. Depending on your security mode, use one of the following commands to create a new secret called mlb-secret in the marathon-lb path. Locating the secret inside the marathon-lb path will ensure that only the Marathon-LB service can access it. The secret will contain the private key, the name of the service account, and other data.

    strict or permissive:

    dcos security secrets create-sa-secret --strict mlb-private-key.pem mlb-principal marathon-lb/mlb-secret
    

    disabled:

    dcos security secrets create-sa-secret mlb-private-key.pem mlb-principal marathon-lb/mlb-secret
    
  2. Ensure the secret was created successfully:
    dcos security secrets list /
    
  3. If you have jq 1.5 or later installed, you can also use the following command to retrieve the secret and ensure that it contains the correct service account ID and private key.
    dcos security secrets get /marathon-lb/mlb-secret --json | jq -r .value | jq
    

    Important: While reviewing the secret, ensure that the login_endpoint URL uses HTTPS if you’re in strict or permissive mode and HTTP if you are in disabled mode. If the URL begins with https and you are in disabled mode, try upgrading the Enterprise DC/OS CLI, deleting the secret, and recreating it.

  4. Now that you have stored the private key in the Secret Store, we recommend deleting the private key file from your file system. This will prevent bad actors from using the private key to authenticate to DC/OS.

    rm -rf mlb-private-key.pem
    
  5. Continue to Provision the service account with permissions.

Using the web interface

  1. Log into the DC/OS web interface as a user with the dcos:superuser permission.

  2. Open the System -> Security tab.

  3. Click New Secret.

  4. Type marathon-lb/mlb-secret into the ID field to create a new secret called mlb-secret in the marathon-lb path. Locating the secret inside the marathon-lb path will ensure that only the Marathon-LB service can access it.

  5. If you have a strict or permissive cluster, paste the following JSON into the Value field.

    {
      "scheme": "RS256",
      "uid": "mlb-principal",
      "private_key": "<private-key-value>",
      "login_endpoint": "https://master.mesos/acs/api/v1/auth/login"
    }
    

    If you have a disabled cluster, paste the following JSON into the Value field.

    {
      "scheme": "RS256",
      "uid": "mlb-principal",
      "private_key": "<private-key-value>",
      "login_endpoint": "http://master.mesos/acs/api/v1/auth/login"
    }
    

    Note: In versions of Marathon-LB prior to 1.3.4, it was necessary to double-base64-encode the private key. Although the private key was already in the PEM format and thus already base64-encoded, you needed to base64-encode it again. This is no longer necessary. In fact, as of Marathon-LB 1.3.4, a double-base64-encoded private key causes a traceback error. Please note that if you follow the instructions in this section and use the DC/OS Enterprise CLI to create the private key as described, you will not end up with a double-base64-encoded private key, nor will you run into this issue.

  6. Replace <private-key-value> with the value of the private key created in Create a key pair.

  7. Click Create. Your secret has been stored!

    Tip: Be sure to copy the path to your secret into a text editor. You will need this later.

  8. Continue to the next section.

Provision the service account with permissions

With the following curl commands you can rapidly provision the Marathon-LB service account with the required permissions. These commands can be executed from outside of the cluster. All you will need is the DC/OS CLI installed. You must also log in via dcos auth login as a superuser.

Prerequisite: If your security mode is permissive or strict, you must follow the steps in Obtaining and passing the DC/OS certificate in curl requests before issuing the curl commands in this section. If your security mode is disabled, you must delete --cacert dcos-ca.crt from the commands before issuing them.

  1. Create the necessary permissions using the following commands.

    Note: There is always a chance that the permission has already been added. If so, the API returns an informative message. Consider this a confirmation and continue to the next one.

    curl -X PUT --cacert dcos-ca.crt -H "Authorization: token=$(dcos config show core.dcos_acs_token)" $(dcos config show core.dcos_url)/acs/api/v1/acls/dcos:service:marathon:marathon:services:%252F -d '{"description":"Allows access to any service launched by the native Marathon instance"}' -H 'Content-Type: application/json'
    curl -X PUT --cacert dcos-ca.crt -H "Authorization: token=$(dcos config show core.dcos_acs_token)" $(dcos config show core.dcos_url)/acs/api/v1/acls/dcos:service:marathon:marathon:admin:events -d '{"description":"Allows access to Marathon events"}' -H 'Content-Type: application/json'
    
  2. Grant the permissions and the allowed action to the service account using the following commands.
    curl -X PUT --cacert dcos-ca.crt -H "Authorization: token=$(dcos config show core.dcos_acs_token)" $(dcos config show core.dcos_url)/acs/api/v1/acls/dcos:service:marathon:marathon:services:%252F/users/mlb-principal/read
    curl -X PUT --cacert dcos-ca.crt -H "Authorization: token=$(dcos config show core.dcos_acs_token)" $(dcos config show core.dcos_url)/acs/api/v1/acls/dcos:service:marathon:marathon:admin:events/users/mlb-principal/read
    
  3. Continue to the next section.

Create a config.json file

About the config.json file

The necessary contents of the config.json file vary according to your security mode.

Strict and permissive mode config.json

If you have called the secret mlb-secret, you can copy and paste the following JSON into a new file and save it with the name config.json. Otherwise, change the name mlb-secret as needed.

{
    "marathon-lb": {
        "secret_name": "marathon-lb/mlb-secret",
        "marathon-uri": "https://marathon.mesos:8443"
    }
}

Note: While switching the port used to communicate with Marathon to 8443 is not required to install Marathon-LB in permissive mode, we do recommend it. This ensures that Marathon-LB’s communications with Marathon occur over an encrypted channel.

Continue to Install Marathon-LB.

Disabled mode config.json

If you have called the secret marathon-lb/mlb-secret, you can copy and paste the following JSON into a new file and save it with the name config.json. Otherwise, change the name marathon-lb/mlb-secret as needed.

{
    "marathon-lb": {
        "secret_name": "marathon-lb/mlb-secret"
    }
}

Continue to the next section.

Install Marathon-LB

To install the service, use the following command.

dcos package install --options=config.json marathon-lb

You can also provide the config.json file to someone else to install Marathon-LB. Please see the Marathon-LB documentation for more information.