From a2251477811cc7e39934cebab04d2b3a8b504e4a Mon Sep 17 00:00:00 2001 From: Tung Nguyen Date: Mon, 27 Dec 2021 19:44:10 +0000 Subject: [PATCH 01/12] backend examples --- _docs/config/backend.md | 15 +- _docs/config/backend/examples.md | 8 + _docs/config/backend/examples/azurerm.md | 81 ++++++++++ _docs/config/backend/examples/gcs.md | 32 ++++ _docs/config/backend/examples/gitlab.md | 67 ++++++++ _docs/config/backend/examples/local.md | 42 +++++ _docs/config/backend/examples/remote.md | 34 ++++ _docs/config/backend/examples/s3.md | 41 +++++ _docs/config/cache-dir.md | 2 + .../config/backend/env-in-bucket-name.md | 5 + _includes/sidebar.html | 8 + _includes/tabs.html | 153 ------------------ 12 files changed, 327 insertions(+), 161 deletions(-) create mode 100644 _docs/config/backend/examples.md create mode 100644 _docs/config/backend/examples/azurerm.md create mode 100644 _docs/config/backend/examples/gcs.md create mode 100644 _docs/config/backend/examples/gitlab.md create mode 100644 _docs/config/backend/examples/local.md create mode 100644 _docs/config/backend/examples/remote.md create mode 100644 _docs/config/backend/examples/s3.md create mode 100644 _includes/config/backend/env-in-bucket-name.md delete mode 100644 _includes/tabs.html diff --git a/_docs/config/backend.md b/_docs/config/backend.md index 1e7d988..24a3f6a 100644 --- a/_docs/config/backend.md +++ b/_docs/config/backend.md @@ -29,9 +29,14 @@ Running: terraspace up demo -Builds a `.terraspace-cache/dev/stacks/demo/backend.tf` using the `config/terraform/backend.tf`. If you want to just build the files without deploying, you can also use `terraspace build`. Below are examples of backends. +Builds a `.terraspace-cache/dev/stacks/demo/backend.tf` using the `config/terraform/backend.tf`. If you want to just build the files without deploying, you can also use `terraspace build`. -{% include tabs.html %} +## Backend Examples + +{% assign docs = site.docs | where: "categories","backend-examples" | sort:"order" %} +{% for doc in docs -%} +* [{{ doc.nav_text }}]({{ doc.url }}) +{% endfor %} ___ @@ -50,9 +55,3 @@ Terraspace expansion will remove the trailing dashes and slashes in case the ins Will result in: us-west-2/dev/demo # notice there's no trailing slash - -___ - -## Why Is Env in Bucket Name? - -By default, the bucket name has the ENV at the end. This is done so we can easily see which environment the bucket stores Terraform statefiles for. This quickly helps with debugging. If you prefer not to have the ENV at the end of the bucket name, remove it after generating the project with `terraspace new project`. \ No newline at end of file diff --git a/_docs/config/backend/examples.md b/_docs/config/backend/examples.md new file mode 100644 index 0000000..a9ec326 --- /dev/null +++ b/_docs/config/backend/examples.md @@ -0,0 +1,8 @@ +--- +title: Backend Examples +--- + +{% assign docs = site.docs | where: "categories","backend-examples" | sort:"order" %} +{% for doc in docs -%} +* [{{ doc.nav_text }}]({{ doc.url }}) +{% endfor %} diff --git a/_docs/config/backend/examples/azurerm.md b/_docs/config/backend/examples/azurerm.md new file mode 100644 index 0000000..eb995c4 --- /dev/null +++ b/_docs/config/backend/examples/azurerm.md @@ -0,0 +1,81 @@ +--- +title: Backend Azurerm +nav_text: Azurerm +categories: backend-examples +order: 2 +--- + +config/terraform/backend.tf: + +{% highlight sh %} +terraform + terraform { + backend "azurerm" { + resource_group_name = "<%= expansion(':ENV-:LOCATION') %>" + storage_account_name = "<%= expansion('ts:SUBSCRIPTION_HASH:LOCATION:ENV') %>" + container_name = "terraform-state" + key = "<%= expansion(':LOCATION/:ENV/:BUILD_DIR/terraform.tfstate') %>" + } +} +{% endhighlight %} + +Notice the variable notation. Terraspace expands it out, substituting the values. The starter `backend.tf` + accounts for `LOCATION`, `ENV`, etc. Here's an expanded example: + +{% highlight sh %} +terraform { + backend "azurerm" { + resource_group_name = "dev-eastus" + storage_account_name = "tswxyzeastusdev" + container_name = "terraform-state" + key = "eastus/dev/stacks/demo/terraform.tfstate" + } +} +{% endhighlight %} + +Note, the `SUBSCRIPTION_HASH` is a short 4-char consistent hash of the longer subscription id. This is useful because azure storage account names are not allowed special characters and are limited to 24 chars. + +## Resource Group Name Thoughts + +The default `resource_group_name` name is env-focused. Azure Resource Groups often make more sense to be app-env scoped. For example: + +app-env focused: + + * app1-dev + * app1-prod + * app2-dev + * app2-prod + +We then know exactly what app and env the resources within the Azure Resource Groups belong to. IE: VMs, DBs, Firewalls, etc. This makes it easy to identify resources as well as clean up resources. + +There are definitely some resources that are more env-focused, though. For example, AKS clusters. It often makes sense to have a dev cluster and deploy your applications onto that cluster. You get container density as a benefit. + +The default `resource_group_name` and is env-focused and accounts for the use-case of shared resources like AKS clusters nicely. + + resource_group_name = "<%= expansion(':ENV-:LOCATION') %>" + +It does not account for app-env focused resources, though. Since Terraspace does not know what app name, it does not include it. One approach is to more dynamically configure resource_group_name like so: + +config/terraform/backend.tf: + +{% highlight sh %} +<% +def resource_group_name + if ENV['APP'] + expansion("#{ENV['APP']}-:ENV-:LOCATION") + else + expansion(":ENV-:LOCATION") + end +end +%> + +terraform { + backend "azurerm" { + resource_group_name = "<%= resource_group_name %>" + storage_account_name = "<%= expansion('ts:SUBSCRIPTION_HASH:LOCATION:ENV') %>" + container_name = "terraform-state" + key = "<%= expansion(':LOCATION/:ENV/:BUILD_DIR/terraform.tfstate') %>" +} +{% endhighlight %} + +If the infrastructure components for the app is really unique, then it may also make sense to have an entirely different terraspace project. diff --git a/_docs/config/backend/examples/gcs.md b/_docs/config/backend/examples/gcs.md new file mode 100644 index 0000000..b209b19 --- /dev/null +++ b/_docs/config/backend/examples/gcs.md @@ -0,0 +1,32 @@ +--- +title: Backend GCS +nav_text: GCS +categories: backend-examples +order: 3 +--- + +config/terraform/backend.tf: + +{% highlight sh %} +terraform + terraform { + backend "gcs" { + bucket = "<%= expansion('terraform-state-:PROJECT-:REGION-:ENV') %>" + prefix = "<%= expansion(':REGION/:ENV/:BUILD_DIR') %>" + } +} +{% endhighlight %} + +Notice the variable notation. Terraspace expands it out, substituting the values. The starter `backend.tf` accounts for `PROJECT`, `ENV`, etc. Here's an expanded example: + +{% highlight sh %} +terraform + terraform { + backend "gcs" { + bucket = "terraform-state-google-project-id-us-central1-dev" + prefix = "us-central1/dev/stacks/demo" + } +} +{% endhighlight %} + +{% include config/backend/env-in-bucket-name.md %} diff --git a/_docs/config/backend/examples/gitlab.md b/_docs/config/backend/examples/gitlab.md new file mode 100644 index 0000000..385a210 --- /dev/null +++ b/_docs/config/backend/examples/gitlab.md @@ -0,0 +1,67 @@ +--- +title: "Backend GitLab" +nav_text: "GitLab" +categories: backend-examples +order: 6 +--- + +config/terraform/backend.tf: + +``` +terraform { + backend "http" { + address = "<%= ENV['GITLAB_PROJECT_URL'] %>/<%= expansion(":ENV-:TYPE_DIR-:MOD_NAME") %>" + lock_address = "<%= ENV['GITLAB_PROJECT_URL'] %>/<%= expansion(":ENV-:TYPE_DIR-:MOD_NAME") %>/lock" + unlock_address = "<%= ENV['GITLAB_PROJECT_URL'] %>/<%= expansion(":ENV-:TYPE_DIR-:MOD_NAME") %>/lock" + username = "<%= ENV['GITLAB_USER'] %>" + password = "<%= ENV['GITLAB_ACCESS_TOKEN'] %>" + lock_method = "POST" + unlock_method = "DELETE" + retry_wait_min = 5 + } +} +``` + +You can set the env var defaults with the [config/boot.rb]({% link _docs/config/boot.md %}) hook. + +config/boot.rb: + +```ruby +ENV['GITLAB_PROJECT_ID'] ||= 'your project id' +ENV['GITLAB_USER'] ||= 'gitlab-user' +ENV['GITLAB_ACCESS_TOKEN'] ||= 'gitlab-api-access-token' +ENV['GITLAB_PROJECT_URL'] = "https://gitlab.com/api/v4/projects/#{ENV['GITLAB_PROJECT_ID']}/terraform/state" +``` + +## Including Region + +When a http backend is used, a generic expander is used and `:REGION` is not expanded. This is because you can use the http backend without any `terraspace_plugin_*` at all . If you want to include `:REGION` in the expansion helper, here's one way to do that: + +config/terraform/backend.tf: + +``` +terraform { + backend "http" { + address = "<%= ENV['GITLAB_PROJECT_URL'] %>/<%= expansion("#{ENV['AWS_REGION']}-:ENV-:TYPE_DIR-:MOD_NAME") %>" + lock_address = "<%= ENV['GITLAB_PROJECT_URL'] %>/<%= expansion("#{ENV['AWS_REGION']}-:ENV-:TYPE_DIR-:MOD_NAME") %>/lock" + unlock_address = "<%= ENV['GITLAB_PROJECT_URL'] %>/<%= expansion("#{ENV['AWS_REGION']}-:ENV-:TYPE_DIR-:MOD_NAME") %>/lock" + username = "<%= ENV['GITLAB_USER'] %>" + password = "<%= ENV['GITLAB_ACCESS_TOKEN'] %>" + lock_method = "POST" + unlock_method = "DELETE" + retry_wait_min = 5 + } +} +``` + +You can set the env var defaults with the [config/boot.rb]({% link _docs/config/boot.md %}) hook. + +config/boot.rb: + +```ruby +ENV['GITLAB_PROJECT_ID'] ||= 'your project id' +ENV['GITLAB_USER'] ||= 'gitlab-user' +ENV['GITLAB_ACCESS_TOKEN'] ||= 'gitlab-api-access-token' +ENV['GITLAB_PROJECT_URL'] = "https://gitlab.com/api/v4/projects/#{ENV['GITLAB_PROJECT_ID']}/terraform/state" +ENV['AWS_REGION'] ||= "us-east-1" +``` diff --git a/_docs/config/backend/examples/local.md b/_docs/config/backend/examples/local.md new file mode 100644 index 0000000..5aef312 --- /dev/null +++ b/_docs/config/backend/examples/local.md @@ -0,0 +1,42 @@ +--- +title: "Backend Local" +nav_text: "Local" +categories: backend-examples +order: 5 +--- + +config/terraform/backend.tf: + +{% highlight sh %} +terraform { + backend "local" { + path = "<%= expansion('.terraform/state.tfstate') %>" + } +} +{% endhighlight %} + +Here's an expanded example: + +{% highlight sh %} +terraform { + backend "local" { + path = ".terraform/state.tfstate" + } +} +{% endhighlight %} + +The local statefile is stored at: + + ls .terraspace-cache/dev/stacks/demo/.terraform/state.tfstate + +If you're wondering how the prefix path `.terraspace-cache/dev/stacks/demo` was determined. It's controlled by + +config/app.rb: + +```ruby +Terraspace.configure do |config| + config.build.cache_dir = ":CACHE_ROOT/:REGION/:ENV/:BUILD_DIR" +end +``` + +For defaults, see: [config/reference]({% link _docs/config/reference.md %}) diff --git a/_docs/config/backend/examples/remote.md b/_docs/config/backend/examples/remote.md new file mode 100644 index 0000000..d29206a --- /dev/null +++ b/_docs/config/backend/examples/remote.md @@ -0,0 +1,34 @@ +--- +title: "Backend Remote: TFC and TFE" +nav_text: "Remote TFC" +categories: backend-examples +order: 4 +--- + +config/terraform/backend.tf: + +{% highlight sh %} +terraform + terraform { + backend "remote" { + organization = "ORG" + workspaces { + name = "<%= expansion(':MOD_NAME-:ENV-:REGION-:INSTANCE') %>" + } + } +} +{% endhighlight %} + +Here's an expanded example: + +{% highlight sh %} +terraform + terraform { + backend "remote" { + organization = "boltops" + workspaces { + name = "demo-dev-us-west-2" + } + } +} +{% endhighlight %} diff --git a/_docs/config/backend/examples/s3.md b/_docs/config/backend/examples/s3.md new file mode 100644 index 0000000..db570f1 --- /dev/null +++ b/_docs/config/backend/examples/s3.md @@ -0,0 +1,41 @@ +--- +title: Backend S3 +nav_text: S3 +categories: backend-examples +order: 1 +--- + +config/terraform/backend.tf: + +{% highlight sh %} +terraform { + backend "s3" { + bucket = "<%= expansion('terraform-state-:ACCOUNT-:REGION-:ENV') %>" + key = "<%= expansion(':REGION/:ENV/:BUILD_DIR/terraform.tfstate') %>" + region = "<%= expansion(':REGION') %>" + encrypt = true + dynamodb_table = "terraform_locks" + } +} +{% endhighlight %} + +Notice the variable notation. Terraspace expands it out, substituting the values. The starter `backend.tf` + accounts for `REGION`, `ENV`, etc. Here's an expanded example: + +{% highlight sh %} +terraform + terraform { + backend "s3" { + bucket = "terraform-state-111111111111-us-west-2-dev" + key = "us-west-2/dev/stacks/demo/terraform.tfstate" + region = "us-west-2" + encrypt = true + dynamodb_table = "terraform_locks" + } +} +{% endhighlight %} + +You can fully control the state file path by adjusting this. The string substitution also makes it clear what + the state path looks like. + +{% include config/backend/env-in-bucket-name.md %} diff --git a/_docs/config/cache-dir.md b/_docs/config/cache-dir.md index bc2b7dc..9633888 100644 --- a/_docs/config/cache-dir.md +++ b/_docs/config/cache-dir.md @@ -22,6 +22,8 @@ The `build.cache_dir` can take: When setting it as a **String**, Terraspace uses it as a pattern and substitute values. For example, +config/app.rb: + ```ruby Terraspace.configure do |config| config.build.cache_dir = ":CACHE_ROOT/:REGION/:ENV/:BUILD_DIR" diff --git a/_includes/config/backend/env-in-bucket-name.md b/_includes/config/backend/env-in-bucket-name.md new file mode 100644 index 0000000..e8adad1 --- /dev/null +++ b/_includes/config/backend/env-in-bucket-name.md @@ -0,0 +1,5 @@ +___ + +## Why Is Env in Bucket Name? + +By default, the bucket name has the ENV at the end. This is done so we can easily see which environment the bucket stores Terraform statefiles for. This quickly helps with debugging. If you prefer not to have the ENV at the end of the bucket name, remove it after generating the project with `terraspace new project`. diff --git a/_includes/sidebar.html b/_includes/sidebar.html index a4b96ee..76512d4 100644 --- a/_includes/sidebar.html +++ b/_includes/sidebar.html @@ -108,6 +108,14 @@
  • App
  • Backend diff --git a/_includes/tabs.html b/_includes/tabs.html deleted file mode 100644 index ef890e6..0000000 --- a/_includes/tabs.html +++ /dev/null @@ -1,153 +0,0 @@ -
    - -
    -
    -
    -{% highlight sh %} -terraform { - backend "s3" { - bucket = "<%= expansion('terraform-state-:ACCOUNT-:REGION-:ENV') %>" - key = "<%= expansion(':REGION/:ENV/:BUILD_DIR/terraform.tfstate') %>" - region = "<%= expansion(':REGION') %>" - encrypt = true - dynamodb_table = "terraform_locks" - } -} -{% endhighlight %} -
    - -

    Notice the variable notation. Terraspace expands it out, substituting the values. The starter backend.tf - accounts for REGION, ENV, etc. Here's an expanded example:

    - -
    -{% highlight sh %} -terraform - terraform { - backend "s3" { - bucket = "terraform-state-111111111111-us-west-2-dev" - key = "us-west-2/dev/stacks/demo/terraform.tfstate" - region = "us-west-2" - encrypt = true - dynamodb_table = "terraform_locks" - } -} -{% endhighlight %} -
    - -

    You can fully control the state file path by adjusting this. The string substitution also makes it clear what - the state path looks like.

    -
    -
    -
    -{% highlight sh %} -terraform - terraform { - backend "azurerm" { - resource_group_name = "<%= expansion(':ENV-:LOCATION') %>" - storage_account_name = "<%= expansion('ts:SUBSCRIPTION_HASH:LOCATION:ENV') %>" - container_name = "terraform-state" - key = "<%= expansion(':LOCATION/:ENV/:BUILD_DIR/terraform.tfstate') %>" - } -} -{% endhighlight %} -
    - -

    Notice the variable notation. Terraspace expands it out, substituting the values. The starter backend.tf - accounts for LOCATION, ENV, etc. Here's an expanded example:

    - -
    - -{% highlight sh %} -terraform { - backend "azurerm" { - resource_group_name = "dev-eastus" - storage_account_name = "tswxyzeastusdev" - container_name = "terraform-state" - key = "eastus/dev/stacks/demo/terraform.tfstate" - } -} -{% endhighlight %} - -
    - -

    Note, the SUBSCRIPTION_HASH is a short 4-char consistent hash of the longer subscription id. This is useful because azure storage account names are not allowed special characters and are limited to 24 chars.

    -
    -
    -
    -{% highlight sh %} -terraform - terraform { - backend "gcs" { - bucket = "<%= expansion('terraform-state-:PROJECT-:REGION-:ENV') %>" - prefix = "<%= expansion(':REGION/:ENV/:BUILD_DIR') %>" - } -} -{% endhighlight %} -
    - -

    Notice the variable notation. Terraspace expands it out, substituting the values. The starter backend.tf accounts for PROJECT, ENV, etc. Here's an expanded example:

    -
    -{% highlight sh %} -terraform - terraform { - backend "gcs" { - bucket = "terraform-state-google-project-id-us-central1-dev" - prefix = "us-central1/dev/stacks/demo" - } -} -{% endhighlight %} -
    - -
    -
    -
    -{% highlight sh %} -terraform - terraform { - backend "remote" { - organization = "ORG" - workspaces { - name = "<%= expansion(':MOD_NAME-:ENV-:REGION-:INSTANCE') %>" - } - } -} -{% endhighlight %} -
    - -

    Here's an expanded example:

    -
    -{% highlight sh %} -terraform - terraform { - backend "remote" { - organization = "boltops" - workspaces { - name = "demo-dev-us-west-2" - } - } -} -{% endhighlight %} -
    - -
    -
    -
    \ No newline at end of file From 9a2557f47cc65b32252c68e0039d226891f457bc Mon Sep 17 00:00:00 2001 From: Tung Nguyen Date: Wed, 29 Dec 2021 15:51:56 +0000 Subject: [PATCH 02/12] improve install shim docs --- _docs/install/bundle-exec.md | 46 +++++++++++++++ _docs/install/gem/multiple-versions.md | 2 +- _docs/install/gem/version-locking.md | 4 +- _docs/install/shim.md | 52 +++++++++++++++++ _docs/install/standalone/centos.md | 4 ++ _docs/misc/shim.md | 80 -------------------------- _includes/sidebar.html | 2 +- 7 files changed, 105 insertions(+), 85 deletions(-) create mode 100644 _docs/install/bundle-exec.md create mode 100644 _docs/install/shim.md delete mode 100644 _docs/misc/shim.md diff --git a/_docs/install/bundle-exec.md b/_docs/install/bundle-exec.md new file mode 100644 index 0000000..c4a8f84 --- /dev/null +++ b/_docs/install/bundle-exec.md @@ -0,0 +1,46 @@ +--- +title: Bundle Exec +--- + +## Already Activated Errors + +If you are seeing an error that says a gem dependency is "already activated", for example: + + You have already activated faraday 1.7.0, but your Gemfile requires faraday 0.17.4. Prepending `bundle exec` to your command may solve this. + +Prepending `bundle exec` should resolve the issue. + +## The Short Answer: Use A Shim + +It can be annoying to remember typing `bundle exec`, though. You can generate a shim to ensure that `bundle exec` is prepended: + + terraspace new shim + +The shim looks something like this: + + #!/bin/bash + if [ -f config/app.rb ]; then + exec bundle exec terraspace "$@" + else + exec terraspace "$@" + fi + +It simply ensures that when you are within a Terraspace project, `bundle exec` is prepended. + +By default, the shim is written to `/usr/local/bin/terraspace`. As long as `/usr/local/bin` is early enough in your system `$PATH`, you can then type `terraspace` instead of `bundle exec terraspace`. + +You can change the path with the `--path` option. More info: [terraspace new shim]({% link _reference/terraspace-new-shim.md %}). + +## The Long Answer: Why? + +The key understanding why the "already activated" error happens is understanding how Ruby, bundler, and system load paths work. The `bundle exec` is essentially a wrapper script that adjusts the load path **before** calling the Ruby world. Using `bundle exec` affects the system load paths. It ensures that the exact versions specified in `Gemfile.lock` are used. + +Example without: + + terraspace version + +Example with: + + bundle exec terraspace version + +When `bundle exec` is not prepended, the gem versions that get used are more dependent on how your environment has been configured. In this case, Ruby usually uses the latest gem dependency versions - it depends on your system load path. Terraspace takes an extra measure to help and calls `bundle exec` early [internally](https://github.com/boltops-tools/terraspace/blob/master/lib/terraspace/autoloader.rb#L2). But it doesn't work for all cases. In this case, you'll need to use `bundle exec`, uninstall other versions of gems from your system, or run `bundle update` to hopefully match gems in `Gemfile.lock` with the other gem versions installed on your system. diff --git a/_docs/install/gem/multiple-versions.md b/_docs/install/gem/multiple-versions.md index d1d6c13..89b5005 100644 --- a/_docs/install/gem/multiple-versions.md +++ b/_docs/install/gem/multiple-versions.md @@ -86,4 +86,4 @@ The code starts to get messy, but it's an option. Instead, the general recommend ## Shim Wrapper -If have multiple versions of terraspace on the same system, you should always use the `bundle exec` command when you're inside the Terraspace project. This ensures that the terraspace version in the project's `Gemfile.lock` is used. Typing `bundle exec` can get old quick, so you can use a [shim wrapper]({% link _docs/misc/shim.md %}) to save yourself previous finger-typing energy. +If have multiple versions of terraspace on the same system, you should always use the `bundle exec` command when you're inside the Terraspace project. This ensures that the terraspace version in the project's `Gemfile.lock` is used. Typing `bundle exec` can get old quick, so you can use a [shim wrapper]({% link _docs/install/shim.md %}) to save yourself previous finger-typing energy. diff --git a/_docs/install/gem/version-locking.md b/_docs/install/gem/version-locking.md index 3200a9c..5b48024 100644 --- a/_docs/install/gem/version-locking.md +++ b/_docs/install/gem/version-locking.md @@ -5,8 +5,6 @@ category: gem order: 1 --- -One of the benefits of installing terraspace as a gem is more control over the installation process. - In the Ruby world locking dependencies are usually handled with [bundler](https://bundler.io/), `Gemfile` and `Gemfile.lock`. The generated Terraspace project with [terraspace new project]({% link _reference/terraspace-new-project.md %}) provides a starter Gemfile. It looks something like this: ```ruby @@ -55,4 +53,4 @@ The issue can also be helped in another way: by reducing the dependencies footpr ## Terrapace Shim Wrapper -On certain system setups, you may also want or need to add a [terraspace shim]({% link _docs/misc/shim.md %}) to ensure that `bundle exec` gets called early enough. It's really system-dependent. Details are covered here: [Shim Wrapper]({% link _docs/misc/shim.md %}). +On certain system setups, you may also want or need to add a [terraspace shim]({% link _docs/install/shim.md %}) to ensure that `bundle exec` gets called early enough. It's really system-dependent. Details are covered here: [Shim Wrapper]({% link _docs/install/shim.md %}). diff --git a/_docs/install/shim.md b/_docs/install/shim.md new file mode 100644 index 0000000..7ef184a --- /dev/null +++ b/_docs/install/shim.md @@ -0,0 +1,52 @@ +--- +title: Shim Wrapper +--- + +## Bundler already activated Warnings + +If you are seeing an error that says a gem dependency is "already activated", for example: + + You have already activated faraday 1.7.0, but your Gemfile requires faraday 0.17.4. Prepending `bundle exec` to your command may solve this. + +Prepending `bundle exec` should resolve the issue. + +## The Short Answer: Use A Shim + +It can be annoying to remember typing `bundle exec`, though. A shim wrapper essentially ensures that `bundle exec` is prepended in front of terraspace when you're within a project. This saves you precious finger-typing energy. You only have to set up the shim once. You can generate a shim with: + + $ terraspace new shim + create /usr/local/bin/terraspace + chmod /usr/local/bin/terraspace + +The shim looks something like this: + + #!/bin/bash + if [ -f config/app.rb ]; then + exec bundle exec terraspace "$@" + else + exec terraspace "$@" + fi + +By default, the shim is written to `/usr/local/bin/terraspace`. As long as `/usr/local/bin` is early enough in your system `$PATH`, you can type `terraspace` instead of `bundle exec terraspace`. + +You can change the path with the `--path` option. More info: [terraspace new shim]({% link _reference/terraspace-new-shim.md %}). + +The shim wrapper should generally work for most systems, it might require adjustments depending on your system. + +## Rbenv Shim Slowness + +If you are using rbenv, it can be [slow](https://github.com/rbenv/rbenv/issues/70) on some systems. You may want to consider replacing the shim that rbenv generates with a faster one. Here's an example: + +~/.rbenv/shims/terraspace + + #!/usr/bin/env bash + EXE=$(gem which terraspace | sed 's|lib/terraspace.rb|exe/terraspace|') + if [ -f config/app.rb ]; then + exec bundle exec $EXE "$@" + else + exec $EXE "$@" + fi + +## Multiple Terraspace Versions + +See: [Multiple Terraspace Versions]({% link _docs/install/gem/multiple-versions.md %}) diff --git a/_docs/install/standalone/centos.md b/_docs/install/standalone/centos.md index e42c923..ff4e9fa 100644 --- a/_docs/install/standalone/centos.md +++ b/_docs/install/standalone/centos.md @@ -57,6 +57,10 @@ You can also download the rpm package and install it directly. Here are the comm rpm -ivh terraspace-latest.rpm terraspace -h +To upgrade an existing install also use the `-U` flag. + + rpm -Uivh terraspace-latest.rpm + You can check [terraspace-latest.rpm.metadata.json](https://yum.boltops.com/packages/terraspace/terraspace-latest.rpm.metadata.json) to verify the package checksum. Here's the checksum command. sha256sum terraspace-latest.rpm diff --git a/_docs/misc/shim.md b/_docs/misc/shim.md deleted file mode 100644 index ff8aa98..0000000 --- a/_docs/misc/shim.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Shim Wrapper ---- - -A shim wrapper can be useful for some cases. - -## Bundler already activated Warnings - -For example, if you've [multiple versions of terraspace installed]({% link _docs/install/gem/multiple-versions.md %}) it can sometimes lead to dependencies resolution issues, and you'll see errors like this: - - You have already activated google-apis-core 0.3.0, but your Gemfile requires google-apis-core 0.2.1. Prepending `bundle exec` to your command may solve this. - -This is due to the ruby system and bundler `Gemfile.lock` dependencies not matching. There are a couple of options: - -1. **bundle update**: Update `Gemfile.lock` with bundle update. -2. **shim wrapper**: Run `bundle exec` in front of your commands with a shim wrapper. - -Approach #1 updates the `Gemfile.lock` dependencies to match the system and removes the warning. You won't need a shim in this case. We'll cover #2 next. - -## Shim Wrapper - -The shim wrapper essentially ensures that `bundle exec` is prepended in front of terraspace when you're within a project. This saves you precious finger-typing energy. You only have to set up the shim once. - -Here's a wrapper shim that will work with rbenv. We'll create it at `~/bin/terraspace` - -~/bin/terraspace - - #!/bin/bash - eval "$(rbenv init -)" - if [ -f config/app.rb ]; then - exec bundle exec terraspace "$@" - else - exec terraspace "$@" - fi - -Make the file executable: - - chmod a+x ~/bin/terraspace - -Then add `~/bin` to your PATH in your `~/.bash_profile` - - export PATH="~/bin:$PATH" - -The wrapper shim will prepend `bundle exec` whenever in a Terraspace project folder with a Gemfile. It will not prepend `bundle exec` outside of a Terraspace project. For example, if you are using `terraspace new project` generator. - -## Generating the Shim Wrapper - -You can also use terraspace to generate the shim wrapper. - - terraspace new shim - -You'll see something like this: - - $ terraspace new shim - create /usr/local/bin/terraspace - chmod /usr/local/bin/terraspace - -If you want to specify the path where you want the shim to be saved like so: - - terraspace new shim --path ~/bin/terraspace - -Note, the shim wrapper contains starter code. Though it should generally work for most systems, it might require adjustments depending on your system. - -## Rbenv Shim Slowness - -If you are using rbenv, it can be [slow](https://github.com/rbenv/rbenv/issues/70) on some systems. You may want to consider replacing the shim that rbenv generates with a faster one. Here's an example: - -~/.rbenv/shims/terraspace - - #!/usr/bin/env bash - EXE=$(gem which terraspace | sed 's|lib/terraspace.rb|exe/terraspace|') - if [ -f config/app.rb ]; then - exec bundle exec $EXE "$@" - else - exec $EXE "$@" - fi - -## Why The Need For bundle exec? - -See: [Multiple Terraspace Versions]({% link _docs/install/gem/multiple-versions.md %}) diff --git a/_includes/sidebar.html b/_includes/sidebar.html index 76512d4..2769aa1 100644 --- a/_includes/sidebar.html +++ b/_includes/sidebar.html @@ -101,6 +101,7 @@
  • Ruby
  • Dependencies
  • Terraform
    • +
  • Shim
  • Config @@ -320,7 +321,6 @@
  • Misc
    • +
  • Non-Cloud + +
  • Terraspace vs Others
  • Config From cb16e977a249b1f144e2a39e803068bcb76bb1c7 Mon Sep 17 00:00:00 2001 From: Tung Nguyen Date: Thu, 30 Dec 2021 17:45:25 +0000 Subject: [PATCH 12/12] update install docs --- _docs/install/docker/versioning.md | 40 +++++++++++++++++++ _docs/install/shim.md | 12 +----- _docs/install/standalone/details.md | 6 +++ .../install/standalone/details/permissions.md | 2 + _includes/install/standalone-shim.md | 11 +++++ 5 files changed, 60 insertions(+), 11 deletions(-) create mode 100644 _docs/install/docker/versioning.md create mode 100644 _includes/install/standalone-shim.md diff --git a/_docs/install/docker/versioning.md b/_docs/install/docker/versioning.md new file mode 100644 index 0000000..cb7729a --- /dev/null +++ b/_docs/install/docker/versioning.md @@ -0,0 +1,40 @@ +--- +title: "Docker Versioning" +nav_text: Versioning +category: docker-guides +--- + +Docker images with terraspace installed are published with the OS and version tag. Dockerhub tags: [boltops/terraspace](https://hub.docker.com/r/boltops/terraspace/tags) + +The version naming convention is: + + boltops/terraspace:$OS-$VERSION + +When the version is not including in the name, it's the latest version of terraspace. + +Examples + + boltops/terraspace:amzn2 # latest + boltops/terraspace:amzn2-0.7.0 + boltops/terraspace:ubuntu # latest + boltops/terraspace:ubuntu-0.7.0 + +More examples: + + boltops/terraspace:alpine + boltops/terraspace:amzn2 + boltops/terraspace:centos + boltops/terraspace:debian + boltops/terraspace:fedora + boltops/terraspace:ubuntu + +## Main Latest Version + +The top-level main latest version is ubuntu. So + + boltops/terraspace + +Is the same as + + boltops/terraspace:ubuntu + diff --git a/_docs/install/shim.md b/_docs/install/shim.md index 34d537f..4a94e2b 100644 --- a/_docs/install/shim.md +++ b/_docs/install/shim.md @@ -31,17 +31,7 @@ The shim wrapper generally work for most systems, it might require adjustments d The [standalone installers]({% link _docs/install/standalone.md %}) actually generate a shim similar to above for you already. It looks something like this: -/usr/local/bin/terraspace - - #!/bin/bash - unset GEM_HOME - unset GEM_PATH - export PATH=/opt/terraspace/embedded/bin:$PATH - if [ -f config/app.rb ]; then - exec bundle exec terraspace "$@" - else - exec terraspace "$@" - fi +{% include install/standalone-shim.md %} ## Rbenv Shim Slowness diff --git a/_docs/install/standalone/details.md b/_docs/install/standalone/details.md index 386a900..8f9b9a4 100644 --- a/_docs/install/standalone/details.md +++ b/_docs/install/standalone/details.md @@ -25,6 +25,12 @@ Most users have `/usr/local/bin` configured in there PATH. So these wrappers sho If you wish not to have these wrappers generated for you, set `export TS_WRAPPERS=0` before running the installer. Without the wrapper scripts, to complete the terraspace standalone installation, you must add `/opt/terraspace/embedded/bin` to your PATH. See: [embedded bin path]({% link _docs/install/standalone/details/path.md %}). +## Terraspace wrapper + +The terraspace wrapper shim is unique in that it ensures that `bundle exec` is prepended when you are within a Terraspace project. It looks something like this: + +{% include install/standalone-shim.md %} + ## Terraform Terraform is not included with the standalone installer. This allows you to install and run the Terraform version you want to use. Here are [Terraform Install instructions]({% link _docs/install/terraform.md %}). diff --git a/_docs/install/standalone/details/permissions.md b/_docs/install/standalone/details/permissions.md index 627b57a..b428507 100644 --- a/_docs/install/standalone/details/permissions.md +++ b/_docs/install/standalone/details/permissions.md @@ -40,3 +40,5 @@ When the `/opt/terraspace` folder is not owned by your user, you won't be able t Password: To fix this issue, make sure `/opt/terraspace` is owned by your user, instead of repeatedly having to type your password for sudo. + +Also, running `sudo` means you're using bare shell with pretty much none of your environment settings or variables configured. Though there are ways to [preserve](https://stackoverflow.com/questions/8633461/how-to-keep-environment-variables-when-using-sudo) environment variables with `--preserve-env`, it's often better to avoid sudo as you'll run into different environmental differences and quirks. diff --git a/_includes/install/standalone-shim.md b/_includes/install/standalone-shim.md new file mode 100644 index 0000000..2f09820 --- /dev/null +++ b/_includes/install/standalone-shim.md @@ -0,0 +1,11 @@ +/usr/local/bin/terraspace + + #!/bin/bash + unset GEM_HOME + unset GEM_PATH + export PATH=/opt/terraspace/embedded/bin:$PATH + if [ -f config/app.rb ]; then + exec bundle exec terraspace "$@" + else + exec terraspace "$@" + fi