From d868a51121eefe781813683705557f26b2a9c265 Mon Sep 17 00:00:00 2001 From: Muhammad Atif Ali Date: Tue, 30 Jan 2024 13:04:05 +0300 Subject: [PATCH 1/6] docs: update modules docs I refactored module docs to remove duplication and hope to achieve a better flow. Also fixed some old links --- docs/templates/modules.md | 122 ++++++++++++++++++++++++-------------- 1 file changed, 78 insertions(+), 44 deletions(-) diff --git a/docs/templates/modules.md b/docs/templates/modules.md index df99cee318d6b..3bd9207735509 100644 --- a/docs/templates/modules.md +++ b/docs/templates/modules.md @@ -35,7 +35,82 @@ and [module sources](https://developer.hashicorp.com/terraform/language/modules/sources) in the Terraform documentation. -## Git authentication +## Coder modules + +Coder publishes plenty of modules that can be used to simlify some common tasks across templates. Some of the modules we publish are, + +1. [`code-server`](https://registry.coder.com/modules/code-server) and [`vscode-web`](https://registry.coder.com/modules/vscode-web) +2. [`git-clone`](https://registry.coder.com/modules/git-clone) +3. [`dotfiles`](https://registry.coder.com/modules/dotfiles) +4. [`jetbrains-gateway`](https://registry.coder.com/modules/jetbrains-gateway) +5. [`jfrog-oauth`](https://registry.coder.com/modules/jfrog-oauth) and [`jfrog-token`](https://registry.coder.com/modules/jfrog-token) +6. [`vault-github`](https://registry.coder.com/modules/vault-github) + +For a full list of available modules please check [Coder module regsitry](https://registry.coder.com/modules). + +## Offline installations + +In offline and restricted deploymnets, there are 2 ways to fetch modules. +1. Artifactory +2. Private git repository + +### Artifactory + +Air gapped users can clone the [coder/modules](htpps://github.com/coder/modules) +repo and publish a +[local terraform module repository](https://jfrog.com/help/r/jfrog-artifactory-documentation/set-up-a-terraform-module/provider-registry) +to resolve modules via [Artifactory](https://jfrog.com/artifactory/). + +1. Create a local-terraform-repository with name `coder-modules-local` +2. Create a virtual repository with name `tf` +3. Follow the below instructions to publish coder modules to Artifactory + + ```shell + git clone https://github.com/coder/modules + cd modules + jf tfc + jf tf p --namespace="coder" --provider="coder" --tag="1.0.0" + ``` + +4. Generate a token with access to the `tf` repo and set an `ENV` variable + `TF_TOKEN_example.jfrog.io="XXXXXXXXXXXXXXX"` on the Coder provisioner. +5. Create a file `.terraformrc` with following content and mount at + `/home/coder/.terraformrc` within the Coder provisioner. + + ```hcl + provider_installation { + direct { + exclude = ["registry.terraform.io/*/*"] + } + network_mirror { + url = "https://example.jfrog.io/artifactory/api/terraform/tf/providers/" + } + } + ``` + +6. Update module source as, + + ```hcl + module "module-name" { + source = "https://example.jfrog.io/tf__coder/module-name/coder" + version = "1.0.0" + agent_id = coder_agent.example.id + ... + } + ``` + +> Do not forget to replace example.jgrog.io with uour Artifactory URL + +Based on the instructions +[here](https://jfrog.com/blog/tour-terraform-registries-in-artifactory/). + +#### Example template + +We have an example template +[here](../../examples/jfrog/remote/main.tf) that uses +our [JFrog Docker](../../examples/jfrog/docker/main.tf) template as the underlying module. + +### Private git repository If you are importing a module from a private git repository, the Coder server or [provisioner](../admin/provisioners.md) needs git credentials. Since this token @@ -65,7 +140,7 @@ If you are running Coder on Docker or Kubernetes, `git` is pre-installed in the Coder image. However, you still need to mount credentials. This can be done via a Docker volume mount or Kubernetes secrets. -### Passing git credentials in Kubernetes +#### Passing git credentials in Kubernetes First, create a `.gitconfig` and `.git-credentials` file on your local machine. You might want to do this in a temporary directory to avoid conflicting with @@ -108,47 +183,6 @@ coder: readOnly: true ``` -## Artifactory - -JFrog Artifactory can serve as a Terraform module registry, allowing you to -simplify a Coder-stored template to a `module` block and input variables. - -With this approach, you can: - -- Easily share templates across multiple Coder instances -- Store templates far larger than the 1MB limit of Coder's template storage -- Apply JFrog platform security policies to your templates - -### Basic Scaffolding - -For example, a template with: - -```hcl -module "frontend" { - source = "cdr.jfrog.io/tf__main/frontend/docker" -} -``` - -References the `frontend` module in the `main` namespace of the `tf` repository. -Remember to replace `cdr.jfrog.io` with your Artifactory instance URL. - -You can upload the underlying module to Artifactory with: - -```shell -# one-time setup commands -# run this on the coder server (or external provisioners, if you have them) -terraform login cdr.jfrog.io; jf tfc --global - -# jf tf p assumes the module name is the same as the current directory name. -jf tf p --namespace=main --provider=docker --tag=v0.0.1 -``` - -### Example template - -We have an example template -[here](https://github.com/coder/coder/tree/main/examples/jfrog/remote) that uses -our [JFrog Docker](../platforms/jfrog.md) template as the underlying module. - ### Next up Learn more about @@ -156,5 +190,5 @@ Learn more about - JFrog's Terraform Registry support [here](https://jfrog.com/help/r/jfrog-artifactory-documentation/terraform-registry). - Configuring the JFrog toolchain inside a workspace - [here](../platforms/jfrog.md). + [here](../guides/artifactory-integration.md). - Coder Module Registry [here](https://registry.coder.com/modules) From 34553398ef93a207a8f34a93bdd71caeac9ff166 Mon Sep 17 00:00:00 2001 From: Muhammad Atif Ali Date: Tue, 30 Jan 2024 13:05:07 +0300 Subject: [PATCH 2/6] Update offline.md --- docs/install/offline.md | 50 +---------------------------------------- 1 file changed, 1 insertion(+), 49 deletions(-) diff --git a/docs/install/offline.md b/docs/install/offline.md index 05cc4281a41c0..e3ce807d8072d 100644 --- a/docs/install/offline.md +++ b/docs/install/offline.md @@ -232,55 +232,7 @@ accessible for your team to use. ## Coder Modules -### Artifactory - -Air gapped users can clone the [coder/modules](htpps://github.com/coder/modules) -repo and publish a -[local terraform module repository](https://jfrog.com/help/r/jfrog-artifactory-documentation/set-up-a-terraform-module/provider-registry) -to resolve modules via [Artifactory](https://jfrog.com/artifactory/). - -1. Create a local-terraform-repository with name `coder-modules-local` -2. Create a virtual repository with name `tf` -3. Follow the below instructions to publish coder modules to Artifactory - - ```shell - git clone https://github.com/coder/modules - cd modules - jf tfc - jf tf p --namespace="coder" --provider="coder" --tag="1.0.0" - ``` - -4. Generate a token with access to the `tf` repo and set an `ENV` variable - `TF_TOKEN_example.jfrog.io="XXXXXXXXXXXXXXX"` on the Coder provisioner. -5. Create a file `.terraformrc` with following content and mount at - `/home/coder/.terraformrc` within the Coder provisioner. - - ```hcl - provider_installation { - direct { - exclude = ["registry.terraform.io/*/*"] - } - network_mirror { - url = "https://example.jfrog.io/artifactory/api/terraform/tf/providers/" - } - } - ``` - -6. Update module source as, - - ```hcl - module "module-name" { - source = "https://example.jfrog.io/tf__coder/module-name/coder" - version = "1.0.0" - agent_id = coder_agent.example.id - ... - } - ``` - -> Do not forget to replace example.jgrog.io with uour Artifactory URL - -Based on the instructions -[here](https://jfrog.com/blog/tour-terraform-registries-in-artifactory/). +To Use Coder modules in offline installations please follow the instrcutiosn [here](../templates/modules.md#offline-installations). ## Firewall exceptions From 1de8b8d3652ffc0879ccca07999c4b6a049d88c7 Mon Sep 17 00:00:00 2001 From: Muhammad Atif Ali Date: Tue, 30 Jan 2024 13:07:09 +0300 Subject: [PATCH 3/6] `make fmt` --- docs/install/offline.md | 3 ++- docs/templates/modules.md | 19 ++++++++++++------- 2 files changed, 14 insertions(+), 8 deletions(-) diff --git a/docs/install/offline.md b/docs/install/offline.md index e3ce807d8072d..ed60703e64ade 100644 --- a/docs/install/offline.md +++ b/docs/install/offline.md @@ -232,7 +232,8 @@ accessible for your team to use. ## Coder Modules -To Use Coder modules in offline installations please follow the instrcutiosn [here](../templates/modules.md#offline-installations). +To Use Coder modules in offline installations please follow the instrcutiosn +[here](../templates/modules.md#offline-installations). ## Firewall exceptions diff --git a/docs/templates/modules.md b/docs/templates/modules.md index 3bd9207735509..73ec9e3baa561 100644 --- a/docs/templates/modules.md +++ b/docs/templates/modules.md @@ -37,20 +37,25 @@ in the Terraform documentation. ## Coder modules -Coder publishes plenty of modules that can be used to simlify some common tasks across templates. Some of the modules we publish are, +Coder publishes plenty of modules that can be used to simlify some common tasks +across templates. Some of the modules we publish are, -1. [`code-server`](https://registry.coder.com/modules/code-server) and [`vscode-web`](https://registry.coder.com/modules/vscode-web) +1. [`code-server`](https://registry.coder.com/modules/code-server) and + [`vscode-web`](https://registry.coder.com/modules/vscode-web) 2. [`git-clone`](https://registry.coder.com/modules/git-clone) 3. [`dotfiles`](https://registry.coder.com/modules/dotfiles) 4. [`jetbrains-gateway`](https://registry.coder.com/modules/jetbrains-gateway) -5. [`jfrog-oauth`](https://registry.coder.com/modules/jfrog-oauth) and [`jfrog-token`](https://registry.coder.com/modules/jfrog-token) +5. [`jfrog-oauth`](https://registry.coder.com/modules/jfrog-oauth) and + [`jfrog-token`](https://registry.coder.com/modules/jfrog-token) 6. [`vault-github`](https://registry.coder.com/modules/vault-github) -For a full list of available modules please check [Coder module regsitry](https://registry.coder.com/modules). +For a full list of available modules please check +[Coder module regsitry](https://registry.coder.com/modules). ## Offline installations In offline and restricted deploymnets, there are 2 ways to fetch modules. + 1. Artifactory 2. Private git repository @@ -106,9 +111,9 @@ Based on the instructions #### Example template -We have an example template -[here](../../examples/jfrog/remote/main.tf) that uses -our [JFrog Docker](../../examples/jfrog/docker/main.tf) template as the underlying module. +We have an example template [here](../../examples/jfrog/remote/main.tf) that +uses our [JFrog Docker](../../examples/jfrog/docker/main.tf) template as the +underlying module. ### Private git repository From 2b94f4c27ddfe21b84067953215476e785acfd05 Mon Sep 17 00:00:00 2001 From: Muhammad Atif Ali Date: Tue, 30 Jan 2024 13:09:16 +0300 Subject: [PATCH 4/6] fix typos --- docs/templates/modules.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/templates/modules.md b/docs/templates/modules.md index 73ec9e3baa561..4e0935ba43690 100644 --- a/docs/templates/modules.md +++ b/docs/templates/modules.md @@ -37,7 +37,7 @@ in the Terraform documentation. ## Coder modules -Coder publishes plenty of modules that can be used to simlify some common tasks +Coder publishes plenty of modules that can be used to simplify some common tasks across templates. Some of the modules we publish are, 1. [`code-server`](https://registry.coder.com/modules/code-server) and @@ -50,7 +50,7 @@ across templates. Some of the modules we publish are, 6. [`vault-github`](https://registry.coder.com/modules/vault-github) For a full list of available modules please check -[Coder module regsitry](https://registry.coder.com/modules). +[Coder module registry](https://registry.coder.com/modules). ## Offline installations From ce4970fd996481d9d801901de92b1de90797f819 Mon Sep 17 00:00:00 2001 From: Muhammad Atif Ali Date: Tue, 30 Jan 2024 15:07:40 +0300 Subject: [PATCH 5/6] fix deadlink --- docs/changelogs/v2.1.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/changelogs/v2.1.0.md b/docs/changelogs/v2.1.0.md index bf7af3379aefb..b18f8e53b33dc 100644 --- a/docs/changelogs/v2.1.0.md +++ b/docs/changelogs/v2.1.0.md @@ -62,7 +62,7 @@ [offline docs](https://www.jetbrains.com/help/idea/fully-offline-mode.html) for JetBrains Gateway (#9039) (@ericpaulsen) - Add `coder login` to CI docs (#9038) (@ericpaulsen) -- Expand [JFrog platform](https://coder.com/docs/v2/latest/platforms/jfrog) and +- Expand [JFrog platform](https://coder.com/docs/v2/v2.1.0/platforms/jfrog) and example template (#9073) (@matifali) ## Container image From 76f3ec438ac37bb09f4ae0e2ca4a75e1dfed7e92 Mon Sep 17 00:00:00 2001 From: Muhammad Atif Ali Date: Tue, 13 Feb 2024 18:30:23 +0300 Subject: [PATCH 6/6] typos --- docs/templates/modules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/templates/modules.md b/docs/templates/modules.md index 4e0935ba43690..94de6cfe88336 100644 --- a/docs/templates/modules.md +++ b/docs/templates/modules.md @@ -104,7 +104,7 @@ to resolve modules via [Artifactory](https://jfrog.com/artifactory/). } ``` -> Do not forget to replace example.jgrog.io with uour Artifactory URL +> Do not forget to replace example.jfrog.io with your Artifactory URL Based on the instructions [here](https://jfrog.com/blog/tour-terraform-registries-in-artifactory/).