Configuring services and pods

ENTERPRISE

Configuring services and pods to use secrets

Your service definition can reference secrets as environment variables or as a file.

File-based secrets

You can reference the secret as a file for increased security from other processes, or if your service needs to read secrets from files mounted in the container. Referencing a file-based secret can be particularly useful for:

  • Kerberos keytabs or other credential files.
  • SSL certificates.
  • Configuration files with sensitive data.

File-based secrets are available in the sandbox of the task ($MESOS_SANDBOX/<configured-path>).

Prerequisites

  • An existing secret. The examples below use a secret called my-secret stored in the developer path. If you complete the steps in Creating secrets, you will meet this prerequisite.

  • DC/OS CLI installed and the DC/OS Enterprise CLI installed.

  • You must get the root cert before issuing the curl commands in this section.

  • The appropriate permissions for your security mode.

    PermissionEnforced in
    dcos:adminrouter:service:marathon fullAll security modes
    dcos:service:marathon:marathon:services:/[service-group fullstrict and permissive security modes

    In strict mode, users may also need the following.

    • dcos:adminrouter:ops:mesos full: to view Task panel information.
    • dcos:adminrouter:ops:slave full: to view the details about the task, including the logs.

    As long as the path of the secret and the path of the group match up properly, the service will be able to access the secret value.

The procedure differs depending on whether or not you want to make the secret available to a pod or to an individual service.

Configuring a service to use a secret

The procedure varies by interface. Refer to the section that corresponds to your desired interface.

Configuring a service to use a secret via the web interface

  1. Log into the web interface as a user with the necessary permissions as discussed in Permissions Management and Granting Access to the Secrets Tab.

  2. Click the Services tab.

  3. Click the + icon in the top right.

    Add a Service

    Figure 1. Running a service

  4. Click the JSON Editor toggle.

  5. Select the contents of the default JSON schema and delete them so that no text is shown in the black box.

  6. Copy one of the following simple application definitions and paste it into the black box. This application definition creates a new service inside of the developer group and references a secret stored inside a developer path.

    Environment variable-based secret:

    1. {
    2.    "id":"/developer/service",
    3.    "cmd":"sleep 100",
    4.    "env":{
    5.       "MY_SECRET":{
    6.          "secret":"secret0"
    7.       }
    8.    },
    9.    "secrets":{
    10.       "secret0":{
    11.          "source":"developer/my-secret"
    12.       }
    13.    }
    14. }

    In the example above, DC/OS stores the secret under the environment variable "MY_SECRET". Observe how the "env" and "secrets" objects are used to define environment variable-based secrets.

    File-based secret:

    1. {
    2.   "id": "developer/service",
    3.   "cmd": "sleep 100",
    4.   "container": {
    5.      "type": "MESOS",
    6.      "volumes": [
    7.       {
    8.         "containerPath": "path",
    9.         "secret": "secretpassword"
    10.       }
    11.     ]
    12.   },
    13.   "secrets": {
    14.     "secretpassword": {
    15.       "source": "developer/databasepassword"
    16.     }
    17.   }
    18. }

    In the example above, the secret will have the filename path and will be available in the task’s sandbox ($MESOS_SANDBOX/path).

    Because the service and the secret paths match, the service will be able to access the secret. See Spaces for more details about the paths.

  7. Click REVIEW & RUN.

  8. Click RUN SERVICE.

  9. Click the group name of your service, for example, developer.

  10. Click the name of your service.

  11. Click the name of its task.

  12. Scroll through the Details tab to locate your DCOS_SECRETS_DIRECTIVE for environmment variable-based secrets.

    If you want to test whether file-based secrets are successful, you can add cat path to the application cmd to have the secret printed to the stdout logs.

    For example:

    1. {
    2.  "id": "developer/service",
    3.  "cmd": "cat path && sleep 100",
    4.  "container": {
    5.    "type": "MESOS",
    6.    "volumes": [
    7.  {
    8.    "containerPath": "path",
    9.    "secret": "secretpassword"
    10.  }
    11.  ]
    12.  },
    13.    "secrets": {
    14.      "secretpassword": {
    15.        "source": "developer/databasepassword"
    16.    }
    17.  }
    18. }

Configuring a service to use an environment variable-based secret via Marathon app definition

  1. Log into the CLI as a user with the necessary permissions via dcos auth login. Refer to About configuring services and pods to use secrets to discover the required permissions.

  2. Within a text editor, create an application definition for your Marathon service. The following application definition creates a new service inside of the developer group and references a secret stored inside a developer path.

    Environment variable-based secret:

    1. {
    2.    "id":"/developer/service",
    3.    "cmd":"sleep 100",
    4.    "env":{
    5.       "MY_SECRET":{
    6.          "secret":"secret0"
    7.       }
    8.    },
    9.    "secrets":{
    10.       "secret0":{
    11.          "source":"developer/my-secret"
    12.       }
    13.    }
    14. }

    In the example above, DC/OS stores the secret under the environment variable "MY_SECRET". Observe how the "env" and "secrets" objects are used to define environment variable-based secrets.

    File-based secret:

    1. {
    2.   "id": "developer/service",
    3.   "cmd": "sleep 100",
    4.   "container": {
    5.      "type": "MESOS",
    6.      "volumes": [
    7.       {
    8.         "containerPath": "path",
    9.         "secret": "secretpassword"
    10.       }
    11.     ]
    12.   },
    13.   "secrets": {
    14.     "secretpassword": {
    15.       "source": "developer/databasepassword"
    16.     }
    17.   }
    18. }

    Because the service group and the secret paths match, the service will be able to access the secret. See Spaces for more details about the paths.

  3. Save the file with a descriptive name, such as myservice.json.

  4. Add the service to DC/OS via the DC/OS CLI.

    1. dcos marathon app add myservice.json

    Alternatively, use the Marathon API to deploy the app as shown below.

    1. curl -X POST --cacert dcos-ca.crt $(dcos config show core.dcos_url)/service/marathon/v2/apps -d @myservice.json -H "Content-type: application/json" -H "Authorization: token=$(dcos config show core.dcos_acs_token)"

  5. Open the DC/OS web interface.

  6. Click the group name of your service, for example, developer.

  7. Click the name of your service.

  8. Click the name of its task.

  9. Scroll through the Details tab to locate your DCOS_SECRETS_DIRECTIVE for environment variable-based secrets.

    If you want to test whether file-based secrets are successful, you can add cat path to the application cmd to have the secret printed to the stdout logs.

    For example:

    1. {
    2.   "id": "developer/service",
    3.   "cmd": "cat path && sleep 100",
    4.   "container": {
    5.     "type": "MESOS",
    6.     "volumes": [
    7.     {
    8.     "containerPath": "path",
    9.     "secret": "secretpassword"
    10.     }
    11.   ]
    12.   },
    13.     "secrets": {
    14.       "secretpassword": {
    15.         "source": "developer/databasepassword"
    16.     }
    17.   }
    18. }

Configuring a pod to use a secret

  1. Log into the CLI as a user with the necessary permissions via dcos auth login. Refer to About configuring services and pods to use secrets for more information about the permissions.

  2. Within a text editor, create an application definition for your pod. You can add the secret using the "environment" and "secrets" objects as shown below. The following simple application defines a new service inside of the developer group and references a secret stored inside a developer path. It stores the secret under the environment variable "MY_SECRET".

    Environment variable-based secret:

    1. {
    2.   "id": "/developer/pod-secret",
    3.   "environment": {
    4.     "MY_SECRET": {
    5.       "secret": "secret0"
    6.     }
    7.   },
    8.   "secrets": {
    9.     "secret0": { "source": "developer/my-secret"}
    10.   },
    11.   "containers": [
    12.     {
    13.       "name": "container-1",
    14.       "resources": {
    15.         "cpus": 0.1,
    16.         "mem": 128
    17.       },
    18.       "exec": {
    19.         "command": {
    20.           "shell": "sleep 3600"
    21.         }
    22.       }
    23.     }
    24.   ],
    25.   "scaling": {
    26.     "kind": "fixed",
    27.     "instances": 1
    28.   },
    29.   "networks": [
    30.     {
    31.       "mode": "host"
    32.     }
    33.   ]
    34. }

    File-based secret:

    1. {
    2.   "id": "developer/pod-with-secrets",
    3.   "containers": [
    4.      {
    5.        "type": "MESOS",
    6.        "name": "container-1",
    7.        "exec": {
    8.          "command": {
    9.            "shell": "sleep 1"
    10.          }
    11.      },
    12.      "volumeMounts": [
    13.        {
    14.          "name": "secretvolume",
    15.          "mountPath": "path/to/db/password"
    16.        }
    17.      ]
    18.    }
    19.  ],
    20.  "volumes": [
    21.    {
    22.      "name": "secretvolume",
    23.      "secret": "secretpassword"
    24.    }
    25.  ],
    26.  "secrets": {
    27.    "secretpassword": {
    28.      "source": "developer/databasepassword"
    29.    }
    30.  }
    31. }

    NOTE: Because the service group and the secret paths match, the pod will be able to access the secret. See Namespacing for more details about the paths.

  3. Save the file with a descriptive name, such as mypod.json.

  4. Use the DC/OS CLI to deploy the pod as shown below.

    1. dcos marathon pod add mypod.json

  5. Open the DC/OS web interface.

  6. Click the group name of your service, for example, developer.

  7. Click the name of your pod.

  8. Click to open the Configuration tab.

  9. Scroll to the Environment Variables area to locate your secret MY_SECRET.

Limitation

The file-based secrets work only with the UCR.