Added executor authentication to the docs. Review: https://reviews.apache.org/r/57667/
Project: http://git-wip-us.apache.org/repos/asf/mesos/repo Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/7dd3b6d1 Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/7dd3b6d1 Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/7dd3b6d1 Branch: refs/heads/master Commit: 7dd3b6d157250895d09e44d4f06b003542b5e36d Parents: 9845086 Author: Greg Mann <[email protected]> Authored: Thu Apr 6 17:16:41 2017 -0700 Committer: Vinod Kone <[email protected]> Committed: Thu Apr 6 17:16:41 2017 -0700 ---------------------------------------------------------------------- docs/authentication.md | 48 +++++++++++++++++++++++++++++++++++++++++- docs/executor-http-api.md | 1 + 2 files changed, 48 insertions(+), 1 deletion(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/mesos/blob/7dd3b6d1/docs/authentication.md ---------------------------------------------------------------------- diff --git a/docs/authentication.md b/docs/authentication.md index 279e00a..6961920 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -94,7 +94,14 @@ Mesos master and agent processes. For more information, refer to the to make HTTP requests to the read-write HTTP endpoints that support authentication. If `false` (the default), these endpoints can be used without authentication. Read-write endpoints are those which can be used to modify the - state of the agent. + state of the agent. Note that for backward compatibility reasons, the V1 + executor API is not affected by this flag. + +* `--[no-]authenticate_http_executors` - If `true`, authentication is required + to make HTTP requests to the V1 executor API. If `false` (the default), that + API can be used without authentication. If this flag is `true` and custom + HTTP authenticators are not specified, then the default `JWT` authenticator is + loaded to handle executor authentication. * `--http_authenticators` - Specifies which HTTP authenticator module to use. The default is `basic`, but additional modules can be added using the @@ -104,6 +111,45 @@ Mesos master and agent processes. For more information, refer to the format) of accepted credentials. This may be optional depending on the authenticator being used. +### Executor + +If HTTP executor authentication is enabled on the agent, then all requests from +HTTP executors must be authenticated. This includes the default executor, HTTP +command executors, and custom HTTP executors. By default, the agent's JSON web +token (JWT) HTTP authenticator is loaded to handle executor authentication on +both the executor and operator API endpoints. Note that command and custom +executors not using the HTTP API will remain unauthenticated. + +When a secret key is loaded via the `--executor_secret_key` flag, the agent will +generate a default JWT for each executor before it is launched. This token is +passed into the executor's environment via the +`MESOS_EXECUTOR_AUTHENTICATION_TOKEN` environment variable. In order to +authenticate with the agent, the executor should place this token into the +`Authorization` header of all its requests as follows: + + Authorization: Bearer MESOS_EXECUTOR_AUTHENTICATION_TOKEN + +In order to upgrade an existing cluster to require executor authentication, the +following procedure should be followed: + +1. Upgrade all agents, and provide each agent with a cryptographic key via the + `--executor_secret_key` flag. This key will be used to sign executor + authentication tokens using the HMAC-SHA256 procedure. + +2. Before executor authentication can be enabled successfully, all HTTP + executors must have executor authentication tokens in their environment and + support authentication. To accomplish this, executors which were already + running before the upgrade must be restarted. This could either be done all + at once, or the cluster may be left in this intermediate state while + executors gradually turn over. + +3. Once all running default/HTTP command executors have been launched by + upgraded agents, and any custom HTTP executors have been upgraded, the agent + processes can be restarted with the `--authenticate_http_executors` flag set. + This will enable required HTTP executor authentication, and since all + executors now have authentication tokens and support authentication, their + requests to the agent will authenticate successfully. + ### Framework If framework authentication is enabled, each framework must be configured to http://git-wip-us.apache.org/repos/asf/mesos/blob/7dd3b6d1/docs/executor-http-api.md ---------------------------------------------------------------------- diff --git a/docs/executor-http-api.md b/docs/executor-http-api.md index c49c234..3e9d04f 100644 --- a/docs/executor-http-api.md +++ b/docs/executor-http-api.md @@ -389,6 +389,7 @@ The following environment variables are set by the agent that can be used by the * `MESOS_AGENT_ENDPOINT`: Agent endpoint (i.e., ip:port to be used by the executor to connect to the agent). * `MESOS_CHECKPOINT`: If set to true, denotes that framework has checkpointing enabled. * `MESOS_EXECUTOR_SHUTDOWN_GRACE_PERIOD`: Amount of time the agent would wait for an executor to shut down (e.g., 60secs, 3mins etc.) after sending a `SHUTDOWN` event. +* `MESOS_EXECUTOR_AUTHENTICATION_TOKEN`: The token the executor should use to authenticate with the agent. When executor authentication is enabled, the agent generates a JSON web token (JWT) that the executor can use to authenticate with the agent's default JWT authenticator. If `MESOS_CHECKPOINT` is set (i.e., if framework checkpointing is enabled), the following additional variables are also set that can be used by the executor for retrying upon a disconnection with the agent:
