diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..0764f3f --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "deploy/ansible-deployment"] + path = deploy/ansible-deployment + url = git@gitlab.hpi.de:maximilian.pass/poseidon-deployment.git diff --git a/deploy/ansible-deployment b/deploy/ansible-deployment new file mode 160000 index 0000000..c6a5566 --- /dev/null +++ b/deploy/ansible-deployment @@ -0,0 +1 @@ +Subproject commit c6a5566e1e901d04b1bcd2aa46383f9d6dfa1e7e diff --git a/docs/resources/client.example.hcl b/docs/resources/client.example.hcl new file mode 100644 index 0000000..c5eed62 --- /dev/null +++ b/docs/resources/client.example.hcl @@ -0,0 +1,15 @@ +client { + enabled = true + servers = [ + "server domain 1", + "server domain 2" + ] +} + +# plugin "docker" { +# config { +# auth { +# config = "/root/.docker/config.json" +# } +# } +# } diff --git a/docs/resources/nomad.example.hcl b/docs/resources/nomad.example.hcl new file mode 100644 index 0000000..c97268e --- /dev/null +++ b/docs/resources/nomad.example.hcl @@ -0,0 +1,28 @@ +# Full configuration options can be found at https://www.nomadproject.io/docs/configuration + +data_dir = "/opt/nomad/data" +bind_addr = "0.0.0.0" + +limits { + http_max_conns_per_client = 0 +} + +# Require TLS +tls { + http = true + rpc = true + + ca_file = "/home/ubuntu/ca.crt" + cert_file = "/home/ubuntu/cert.crt" + key_file = "/home/ubuntu/cert-key.pem" + + verify_server_hostname = true + verify_https_client = true +} + +# telemetry { +# collection_interval = "10s" +# prometheus_metrics = true +# publish_allocation_metrics = true +# publish_node_metrics = true +# } diff --git a/docs/poseidon_policy.hcl b/docs/resources/poseidon_policy.hcl similarity index 100% rename from docs/poseidon_policy.hcl rename to docs/resources/poseidon_policy.hcl diff --git a/docs/resources/server.example.hcl b/docs/resources/server.example.hcl new file mode 100644 index 0000000..4bf641a --- /dev/null +++ b/docs/resources/server.example.hcl @@ -0,0 +1,14 @@ +server { + enabled = true + bootstrap_expect = 2 + server_join { + retry_join = ["<>"] + retry_max = 3 + retry_interval = "15s" + } + + # https://www.nomadproject.io/docs/configuration/server + default_scheduler_config { + scheduler_algorithm = "spread" + } +} diff --git a/docs/security.md b/docs/security.md index d66a871..cd8f949 100644 --- a/docs/security.md +++ b/docs/security.md @@ -1,5 +1,31 @@ # Security configurations +## TLS + +⚠️ We highly encourage the use of TLS in this API to increase the security. + +### Poseidon + +To enable TLS, you need to create an appropriate certificate first. +You can do this in the same way [as for Nomad](https://learn.hashicorp.com/tutorials/nomad/security-enable-tls): +- `cfssl print-defaults csr | cfssl gencert -initca - | cfssljson -bare poseidon-ca` +- Copy `cfssl.json` +- `echo '{}' | cfssl gencert -ca=poseidon-ca.pem -ca-key=poseidon-ca-key.pem -config=cfssl.json -hostname="<>,localhost,127.0.0.1" - | cfssljson -bare poseidon-server` + + +Then, set `server.tls.active` or the corresponding environment variable to `true` and specify the `server.tls.certfile` and `server.tls.keyfile` options. + +### Nomad + +To enable TLS between Poseidon and Nomad, TLS needs to be first activated in Nomad. See [the Nomad documentation](https://learn.hashicorp.com/collections/nomad/transport-security) for a guideline on how to do that. + +Afterwards, it is *required* to set the `nomad.tls.active` config option to `true`, as Nomad will no longer accept any connections over HTTP. To make sure the authenticity of the Nomad host can be validated, the `nomad.tls.cafile` option has to point to a certificate of the signing authority. + +If using mutual TLS between Poseidon and Nomad is desired, the `nomad.tls.certfile` and `nomad.tls.keyfile` options can hold a client certificate. This certificate must be signed by the same CA as the certificates of the Nomad hosts. Note that mTLS can (and should) be enforced by Nomad in this case using the [verify_https_client](https://www.nomadproject.io/docs/configuration/tls#verify_https_client) configuration option. + +Here are sample configurations for [all Nomad nodes](resources/nomad.example.hcl), [the Nomad servers](resources/server.example.hcl) and [the Nomad clients](resources/client.example.hcl). + + ## Authentication ⚠️ Don't use authentication without TLS enabled, as otherwise the token will be transmitted in clear text. @@ -20,9 +46,10 @@ $ curl -H "Poseidon-Token: SECRET" http://localhost:7200/api/v1/some-protected-r ### Nomad -⚠️ Enabling access control in the Nomad cluster is also recommended, to avoid having unauthorized actors perform unwanted actions in the cluster. Instructions on setting up the cluster appropriately can be found in [the Nomad documentation](https://learn.hashicorp.com/collections/nomad/access-control). +An alternative or additional measure to mTLS (as mentioned above) is to enable access control in the Nomad cluster to prevent unauthorised actors from performing unwanted actions in the cluster. + Instructions on setting up the cluster appropriately can be found in [the Nomad documentation](https://learn.hashicorp.com/collections/nomad/access-control). -Afterwards, it is recommended to create a specific [Access Policy](https://learn.hashicorp.com/tutorials/nomad/access-control-policies?in=nomad/access-control) for Poseidon with the minimal set of capabilities it needs for operating the cluster. A non-minimal example with complete permissions can be found [here](docs/poseidon_policy.hcl). Poseidon requires a corresponding [Access Token](https://learn.hashicorp.com/tutorials/nomad/access-control-tokens?in=nomad/access-control) to send commands to Nomad. A Token looks like this: +Afterwards, it is recommended to create a specific [Access Policy](https://learn.hashicorp.com/tutorials/nomad/access-control-policies?in=nomad/access-control) for Poseidon with the minimal set of capabilities it needs for operating the cluster. A non-minimal example with complete permissions can be found [here](resources/poseidon_policy.hcl). Poseidon requires a corresponding [Access Token](https://learn.hashicorp.com/tutorials/nomad/access-control-tokens?in=nomad/access-control) to send commands to Nomad. A Token looks like this: ```text Accessor ID = 463d3216-dc16-570f-380c-a48f5d26d955 @@ -41,20 +68,3 @@ The `Secret ID` of the Token needs to be specified as the value of `nomad.token` Once configured, all requests to the Nomad API automatically contain a `X-Nomad-Token` header containing the token. ⚠️ Make sure that no (overly permissive) `anonymous` access policy is present in the cluster after the policy for Poseidon has been added. Anyone can perform actions as specified by this special policy without authenticating! - -## TLS - -We highly encourage the use of TLS in this API to increase the security. - -### Poseidon - -To enable TLS, you need to create an appropriate certificate first. Then, -set `server.tls.active` or the corresponding environment variable to `true` and specify the `server.tls.certfile` and `server.tls.keyfile` options. - -### Nomad - -To enable TLS between Poseidon and Nomad, TLS needs to be first activated in Nomad. See [the Nomad documentation](https://learn.hashicorp.com/collections/nomad/transport-security) for a guideline on how to do that. - -Afterwards, it is *required* to set the `nomad.tls.active` config option to `true`, as Nomad will no longer accept any connections over HTTP. To make sure the authenticity of the Nomad host can be validated, the `nomad.tls.cafile` option has to point to a certificate of the signing authority. - -If using mutual TLS between Poseidon and Nomad is desired, the `nomad.tls.certfile` and `nomad.tls.keyfile` options can hold a client certificate. This certificate must be signed by the same CA as the certificates of the Nomad hosts. Note that mTLS can (and should) be enforced by Nomad in this case using the [verify_https_client](https://www.nomadproject.io/docs/configuration/tls#verify_https_client) configuration option.