diff --git a/website/source/docs/drivers/custom.html.md b/website/source/docs/drivers/custom.html.md index 53f30939e..7f2bde558 100644 --- a/website/source/docs/drivers/custom.html.md +++ b/website/source/docs/drivers/custom.html.md @@ -3,17 +3,14 @@ layout: "docs" page_title: "Drivers: Custom" sidebar_current: "docs-drivers-custom" description: |- - Create custom secret backends for Nomad. + Create custom task drivers for Nomad. --- # Custom Drivers -Nomad does not currently support the creation of custom secret backends. -The primary reason is because we want to ensure the core of Nomad is -secure before attempting any sort of plug-in system. We're interested -in supporting custom secret backends, but do not yet have a clear strategy -or timeline to do. +Nomad does not currently support pluggable task drivers, however the +interface that a task driver must implement is minimal. In the short term, +custom drivers can be implemented in Go and compiled into the binary, +however in the long term we plan to expose a plugin interface such that +task drivers can be dynamically registered without recompiling the Nomad binary. -In the mean time, you can use the -[generic backend](/docs/secrets/generic/index.html) to support custom -data with custom leases. diff --git a/website/source/docs/drivers/docker.html.md b/website/source/docs/drivers/docker.html.md new file mode 100644 index 000000000..d9bb939c1 --- /dev/null +++ b/website/source/docs/drivers/docker.html.md @@ -0,0 +1,14 @@ +--- +layout: "docs" +page_title: "Drivers: Docker" +sidebar_current: "docs-drivers-docker" +description: |- + The Docker task driver is used to run Docker based tasks. +--- + +# Docker Driver + +Name: `docker` + +TODO + diff --git a/website/source/docs/drivers/docker/index.html.md b/website/source/docs/drivers/docker/index.html.md deleted file mode 100644 index ee88d0a96..000000000 --- a/website/source/docs/drivers/docker/index.html.md +++ /dev/null @@ -1,358 +0,0 @@ ---- -layout: "docs" -page_title: "Drivers: Docker" -sidebar_current: "docs-drivers-docker" -description: |- - The AWS secret backend for Nomad generates access keys dynamically based on IAM policies. ---- - -# Docker Driver - -Name: `aws` - -The AWS secret backend for Nomad generates AWS access credentials dynamically -based on IAM policies. This makes IAM much easier to use: credentials could -be generated on the fly, and are automatically revoked when the Nomad -lease is expired. - -This page will show a quick start for this backend. For detailed documentation -on every path, use `vault path-help` after mounting the backend. - -## Quick Start - -The first step to using the aws backend is to mount it. -Unlike the `generic` backend, the `aws` backend is not mounted by default. - -```text -$ vault mount aws -Successfully mounted 'aws' at 'aws'! -``` - -Next, we must configure the root credentials that are used to manage IAM credentials: - -```text -$ vault write aws/config/root \ - access_key=AKIAJWVN5Z4FOFT7NLNA \ - secret_key=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 \ - region=us-east-1 -``` - -The following parameters are required: - -- `access_key` - the AWS access key that has permission to manage IAM - credentials. -- `secret_key` - the AWS secret key that has permission to manage IAM - credentials. -- `region` the AWS region for API calls. - -The next step is to configure a role. A role is a logical name that maps -to a policy used to generated those credentials. For example, lets create -a "deploy" role: - -```text -$ vault write aws/roles/deploy \ - name=deploy \ - policy=@policy.json -``` - -This path will create a named role along with the IAM policy used -to restrict permissions for it. This is used to dynamically create -a new pair of IAM credentials when needed. - -The `@` tells Nomad to load the policy from the file named `policy.json`. Here -is an example IAM policy to get started: - -```javascript -{ - "Version": "2012-10-17", - "Statement": { - "Effect": "Allow", - "Action": "iam:*", - "Resource": "*" - } -} -``` - -For more information on IAM policies, please see the -[AWS IAM policy documentation](http://docs.aws.amazon.com/IAM/latest/UserGuide/PoliciesOverview.html). - -To generate a new set of IAM credentials, we simply read from that role: - -```text -$ vault read aws/creds/deploy -Key Value -lease_id aws/creds/deploy/7cb8df71-782f-3de1-79dd-251778e49f58 -lease_duration 3600 -access_key AKIAIOMYUTSLGJOGLHTQ -secret_key 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 -``` - -If you run the command again, you will get a new set of credentials: - -```text -$ vault read aws/creds/deploy -Key Value -lease_id aws/creds/deploy/82d89562-ff19-382e-6be9-cb45c8f6a42d -lease_duration 3600 -access_key AKIAJZ5YRPHFH3QHRRRQ -secret_key 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 -``` - -If you get an error message similar to either of the following, the root credentials that you wrote to `aws/config/root` have insufficient privilege: - -```text -$ vault read aws/creds/deploy -* Error creating IAM user: User: arn:aws:iam::000000000000:user/hashicorp is not authorized to perform: iam:CreateUser on resource: arn:aws:iam::000000000000:user/vault-root-1432735386-4059 - -$ vault revoke aws/creds/deploy/774cfb27-c22d-6e78-0077-254879d1af3c -Revoke error: Error making API request. - -URL: PUT http://127.0.0.1:8200/v1/sys/revoke/aws/creds/deploy/774cfb27-c22d-6e78-0077-254879d1af3c -Code: 400. Errors: - -* invalid request -``` - -The root credentials need permission to perform various IAM actions. These are the actions that the AWS secret backend uses to manage IAM credentials. Here is an example IAM policy that would grant these permissions: - -```javascript -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "iam:CreateAccessKey", - "iam:CreateUser", - "iam:PutUserPolicy", - "iam:ListGroupsForUser", - "iam:ListUserPolicies", - "iam:ListAccessKeys", - "iam:DeleteAccessKey", - "iam:DeleteUserPolicy", - "iam:RemoveUserFromGroup", - "iam:DeleteUser" - ], - "Resource": [ - "arn:aws:iam::ACCOUNT-ID-WITHOUT-HYPHENS:user/vault-*" - ] - } - ] -} -``` - -Note that this policy example is unrelated to the policy you wrote to `aws/roles/deploy`. This policy example should be applied to the IAM user (or role) associated with the root credentials that you wrote to `aws/config/root`. You have to apply it yourself in IAM. The policy you wrote to `aws/roles/deploy` is the policy you want the AWS secret backend to apply to the temporary credentials it returns from `aws/creds/deploy`. - -If you get stuck at any time, simply run `vault path-help aws` or with a subpath for -interactive help output. - -## API - -### /aws/config/root -#### POST - -
-
Description
-
- Configures the root IAM credentials used. - This is a root protected endpoint. -
- -
Method
-
POST
- -
URL
-
`/aws/config/root`
- -
Parameters
-
- -
- -
Returns
-
- A `204` response code. -
-
- -### /aws/config/lease -#### POST - -
-
Description
-
- Configures the lease settings for generated credentials. - This is a root protected endpoint. -
- -
Method
-
POST
- -
URL
-
`/aws/config/lease`
- -
Parameters
-
- -
- -
Returns
-
- A `204` response code. -
-
- -### /aws/roles/ -#### POST - -
-
Description
-
- Creates or updates a named role. -
- -
Method
-
POST
- -
URL
-
`/aws/roles/`
- -
Parameters
-
- -
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Queries a named role. -
- -
Method
-
GET
- -
URL
-
`/aws/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "policy": "..." - } - } - ``` - -
-
- -#### DELETE - -
-
Description
-
- Deletes a named role. -
- -
Method
-
DELETE
- -
URL
-
`/aws/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
- - -### /aws/creds/ -#### GET - -
-
Description
-
- Generates a dynamic IAM credential based on the named role. -
- -
Method
-
GET
- -
URL
-
`/aws/creds/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "access_key": "...", - "secret_key": "..." - } - } - ``` - -
-
diff --git a/website/source/docs/drivers/exec.html.md b/website/source/docs/drivers/exec.html.md new file mode 100644 index 000000000..03286208e --- /dev/null +++ b/website/source/docs/drivers/exec.html.md @@ -0,0 +1,14 @@ +--- +layout: "docs" +page_title: "Drivers: Exec" +sidebar_current: "docs-drivers-exec" +description: |- + The Exec task driver is used to run binaries using OS isolation primitives. +--- + +# Fork/Exec Driver + +Name: `exec` + +TODO + diff --git a/website/source/docs/drivers/index.html.md b/website/source/docs/drivers/index.html.md index 4175c7e8e..e5a950392 100644 --- a/website/source/docs/drivers/index.html.md +++ b/website/source/docs/drivers/index.html.md @@ -1,75 +1,24 @@ --- layout: "docs" -page_title: "Drivers" +page_title: "Task Drivers" sidebar_current: "docs-drivers" description: |- - Secret backends are mountable backends that store or generate secrets in Nomad. + Task Drivers are used to integrate with the host OS to run tasks in Nomad. --- -# Drivers +# Task Drivers -Secret backends are the components in Nomad which store and generate -secrets. +Task drivers are used by Nomad clients to execute a task and provide resource +isolation. By having extensible task drivers, Nomad has the flexibility to +support a broad set of workloads across all major operating systems. -Some secret backends, such as "generic", simply store and read -secrets verbatim. Other secret backends, such as "aws", create _dynamic -secrets_: secrets that are made on demand. +The list of supported task is on the left. Each task driver documents the +configuration available in a job specification, the environments it can be +used in, and the resource isolation mechanisms available. -Secret backends are part of the -[mount system](#) -in Nomad. They behave very similarly to a virtual filesystem: -any read/write/delete is sent to the secret backend, and the secret -backend can choose to react to that operation however it sees fit. +Nomad strives to mask the details of running a task from users and instead +provides a clean abstraction. It is possible for the same task to be executed +with different isolation levels depending on the client running the task. +The goal is to use the strictest isolation available and gracefully degrade +protections where necessary. -For example, the "generic" backend passes through any operation back -to the configured storage backend for Nomad. A "read" turns into a -"read" of the storage backend at the same path, a "write" turns into -a write, etc. This is a lot like a normal filesystem. - -The "aws" backend, on the other hand, behaves differently. When you -write to `aws/config/root`, it expects a certain format and stores that -information as configuration. You cannot read from this path. When you -read from `aws/`, it looks up an IAM policy named `` and -generates AWS access credentials on demand and returns them. It does not -behave at all like a typical filesystem: you are not simply storing and -retrieving values, you are interacting with an API. - -## Mounting/Unmounting Secret Backends - -Secret backends can be mounted/unmounted using the CLI or the API. -There are three operations that can be performed with a secret backend -with regards to mounting: - - * **Mount** - This mounts a new secret backend. Multiple secret - backends of the same type can be mounted at the same time by - specifying different mount points. By default, secret backends are - mounted to the same path as their name. This is what you want most - of the time. - - * **Unmount** - This unmounts an existing secret backend. When a secret - backend is unmounted, all of its secrets are revoked (if they support - it), and all of the data stored for that backend in the physical storage - layer is deleted. - - * **Remount** - This moves the mount point for an existing secret backend. - This revokes all secrets, since secret leases are tied to the path they - were created at. The data stored for the backend will not be deleted. - -Once a secret backend is mounted, you can interact with it directly -at its mount point according to its own API. You can use the `vault path-help` -system to determine the paths it responds to. - -## Barrier View - -An important concept around secret backends is that they receive a -_barrier view_ to the configured Nomad physical storage. This is a lot -like a [chroot](http://en.wikipedia.org/wiki/Chroot). - -Whenever a secret backend is mounted, a random UUID is generated. This -becomes the data root for that backend. Whenever that backend writes to -the physical storage layer, it is prefixed with that UUID folder. Since -the Nomad storage layer does not support relative access (such as `..`), -this makes it impossible for a mounted backend to access any other data. - -This is an important security feature in Nomad: even a malicious backend -cannot access the data from any other backend. diff --git a/website/source/docs/drivers/java.html.md b/website/source/docs/drivers/java.html.md new file mode 100644 index 000000000..130fc999b --- /dev/null +++ b/website/source/docs/drivers/java.html.md @@ -0,0 +1,14 @@ +--- +layout: "docs" +page_title: "Drivers: Java" +sidebar_current: "docs-drivers-java" +description: |- + The Java task driver is used to run Jars using the JVM. +--- + +# Java Driver + +Name: `java` + +TODO + diff --git a/website/source/docs/drivers/qemu.html.md b/website/source/docs/drivers/qemu.html.md new file mode 100644 index 000000000..f617179f5 --- /dev/null +++ b/website/source/docs/drivers/qemu.html.md @@ -0,0 +1,14 @@ +--- +layout: "docs" +page_title: "Drivers: Qemu" +sidebar_current: "docs-drivers-qemu" +description: |- + The Qemu task driver is used to run virtual machines using Qemu/KVM. +--- + +# Qemu Driver + +Name: `qemu` + +TODO + diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index a0af2ed94..6a0ec604e 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -94,22 +94,22 @@
> - Drivers + Task Drivers