diff --git a/docs/src/getting_started.md b/docs/src/getting_started.md index f6b4cba..d1b16dc 100644 --- a/docs/src/getting_started.md +++ b/docs/src/getting_started.md @@ -175,7 +175,7 @@ $ ansible-inventory --graph --vars $ ansible-playbook main.yml ``` -The playbook will perform the following idempotently: +The playbook will perform the following: 1. Create a root and intermediate CA for Vault 2. Configure Vault to use new CA @@ -196,3 +196,31 @@ existing state in the `terraform/vault` subdirectory if a different `vault_terraform_workspace` is not provided. This WILL result in permanent data loss and care should be taken when running the role (and playbook) on multiple clusters or servers. + +## Post Setup + +### Smoke Tests + +Smoke tests are performed with [goss](https://github.com/goss-org/goss) as part +of the `main.yml` playbook to ensure all required software are installed and +running. + +>**Note**: The included goss files are static with hardcoded information. As +>such, they will fail if some of the Ansible default variables are changed (eg. +>username, NFS mountpoints). See +>[issues](./references/issues.md#static-goss-files) for details on a workaround. + +### Running Applications + +After verifying that the cluster is up and running, we can begin to run +applications on it with Nomad jobs. This project provides a number of Nomad +jobspec files in `terraform/nomad/apps` to be run with Terraform with the +following features: + +- With Vault integration configured, Nomad supports the fetching of application +secrets with Vault +- Traefik as a reverse proxy +- (Optional) Postgres as a database (with Vault-managed DB credentials) + +See [Adding a New Application](./apps/add_new.md) for details on onboarding a +new application to Nomad. diff --git a/docs/src/references/issues.md b/docs/src/references/issues.md index 707e808..392b9d3 100644 --- a/docs/src/references/issues.md +++ b/docs/src/references/issues.md @@ -23,3 +23,20 @@ is [not supported](https://github.com/hashicorp/vault/issues/20538).~ [#18562](https://github.com/hashicorp/vault/issues/18562). A [fix](https://github.com/hashicorp/vault/pull/19002) is available in Vault 1.14.~ + +## Static Goss Files + +The provided goss files in `ansible/goss` contain hardcoded information that can +cause the smoke tests to fail if some Ansible variables are modified: + +- common_user +- common_nfs_dir +- common_packages + +The temporary workaround is to create your own goss files, edit the given goss +files or to simply comment out the smoke test tasks. + +To fix this, goss +[supports](https://github.com/goss-org/goss/blob/master/docs/gossfile.md#templates) +templating to create dynamic goss files. The `ansible_collection.goss` role must +be modified to add support for dynamic tests.