docs: explain using Artifactory as a template store (#9071)

ammario · web-flow · commit 95d66ac3859f · 2023-08-15T16:46:56.000-05:00
diff --git a/docs/platforms/jfrog.md b/docs/platforms/jfrog.md
@@ -5,7 +5,7 @@ Use Coder and JFrog together to secure your development environments without dis
 This guide will demonstrate how to use JFrog Artifactory as a package registry
 within a workspace. We'll use Docker as the underlying compute. But, these concepts apply to any compute platform.
 
-The full example template can be found [here](https://github.com/coder/coder/tree/main/examples/templates/jfrog-docker).
+The full example template can be found [here](https://github.com/coder/coder/tree/main/examples/templates/jfrog/docker).
 
 ## Requirements
 
@@ -74,7 +74,7 @@ coder templates push --var 'jfrog_host=YYY.jfrog.io' --var 'artifactory_access_t
 we'll focus on its ability to configure package managers, as that's the relevant
 functionality for most developers.
 
-The generic method of installing the JFrog CLI is the following command:
+Most users should be able to install `jf` by running the following command:
 
 ```sh
 curl -fL https://install-cli.jfrog.io | sh
@@ -165,7 +165,7 @@ Default:                        true
 
 ## Installing the JFrog VS Code Extension
 
-You can install the JFrog VS Code extension into workspaces automatically
+You can install the JFrog VS Code extension into workspaces
 by inserting the following lines into your `startup_script`:
 
 ```sh
@@ -228,5 +228,6 @@ supported by Artifactory. See the [JFrog documentation](https://jfrog.com/help/r
 
 ## More reading
 
-- See the full example template [here](https://github.com/coder/coder/tree/main/examples/templates/jfrog-docker).
+- See the full example template [here](https://github.com/coder/coder/tree/main/examples/templates/jfrog/docker).
 - To serve extensions from your own VS Code Marketplace, check out [code-marketplace](https://github.com/coder/code-marketplace#artifactory-storage).
+- To store templates in Artifactory, check out our [Artifactory modules](../templates/modules.md#artifactory) docs.
diff --git a/docs/templates/modules.md b/docs/templates/modules.md
@@ -87,3 +87,50 @@ coder:
       subPath: .git-credentials
       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:
+
+```console
+# 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/templates/jfrog/remote) that uses our [JFrog Docker](../platforms/jfrog.md) template
+as the underlying module.
+
+### Next up
+
+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).
diff --git a/examples/templates/jfrog/docker/README.md b/examples/templates/jfrog/docker/README.md
@@ -5,7 +5,7 @@ tags: [local, docker, jfrog]
 icon: /icon/docker.png
 ---
 
-# jfrog-docker
+# docker
 
 To get started, run `coder templates init`. When prompted, select this template.
 Follow the on-screen instructions to proceed.
diff --git a/examples/templates/jfrog/docker/build/Dockerfile b/examples/templates/jfrog/docker/build/Dockerfile
diff --git a/examples/templates/jfrog/docker/main.tf b/examples/templates/jfrog/docker/main.tf
@@ -16,11 +16,9 @@ terraform {
 }
 
 locals {
-  # if the jfrog username is same as the coder username, you can use the following
-  # artifactory_username = data.coder_workspace.me.owner
-  # if the username is same as email, you can use the following
-  # artifactory_username = urlencode(data.coder_workspace.me.owner_email)
-  artifactory_username = data.coder_workspace.me.owner
+  # take care to use owner_email instead of owner because users can change
+  # their username.
+  artifactory_username = data.coder_workspace.me.owner_email
   artifactory_repository_keys = {
     "npm"    = "npm"
     "python" = "python"
@@ -55,7 +53,9 @@ provider "artifactory" {
 }
 
 resource "artifactory_scoped_token" "me" {
-  username = local.artifactory_username
+  # This is hacky, but on terraform plan the data source gives empty strings,
+  # which fails validation.
+  username = length(local.artifactory_username) > 0 ? local.artifactory_username : "plan"
 }
 
 resource "coder_agent" "main" {
@@ -125,13 +125,13 @@ resource "docker_volume" "home_volume" {
 resource "docker_image" "main" {
   name = "coder-${data.coder_workspace.me.id}"
   build {
-    context = "./build"
+    context = "${path.module}/build"
     build_args = {
       USER = local.workspace_user
     }
   }
   triggers = {
-    dir_sha1 = sha1(join("", [for f in fileset(path.module, "build/*") : filesha1(f)]))
+    dir_sha1 = sha1(join("", [for f in fileset(path.module, "build/*") : filesha1("${path.module}/${f}")]))
   }
 }
 
diff --git a/examples/templates/jfrog/remote/main.tf b/examples/templates/jfrog/remote/main.tf
@@ -0,0 +1,16 @@
+module "docker" {
+  source                   = "cdr.jfrog.io/tf__main/docker/docker"
+  jfrog_host               = var.jfrog_host
+  artifactory_access_token = var.artifactory_access_token
+}
+
+variable "jfrog_host" {
+  type        = string
+  description = "JFrog instance hostname. For example, 'YYY.jfrog.io'."
+}
+
+variable "artifactory_access_token" {
+  type        = string
+  description = "The admin-level access token to use for JFrog."
+}
+

Original file line number	Diff line number	Diff line change
`@@ -16,11 +16,9 @@ terraform {`
`16`	`16`	`}`
`17`	`17`
`18`	`18`	`locals {`
`19`		`- # if the jfrog username is same as the coder username, you can use the following`
`20`		`- # artifactory_username = data.coder_workspace.me.owner`
`21`		`- # if the username is same as email, you can use the following`
`22`		`- # artifactory_username = urlencode(data.coder_workspace.me.owner_email)`
`23`		`- artifactory_username = data.coder_workspace.me.owner`
	`19`	`+ # take care to use owner_email instead of owner because users can change`
	`20`	`+ # their username.`
	`21`	`+ artifactory_username = data.coder_workspace.me.owner_email`
`24`	`22`	`artifactory_repository_keys = {`
`25`	`23`	`"npm" = "npm"`
`26`	`24`	`"python" = "python"`
`@@ -55,7 +53,9 @@ provider "artifactory" {`
`55`	`53`	`}`
`56`	`54`
`57`	`55`	`resource "artifactory_scoped_token" "me" {`
`58`		`- username = local.artifactory_username`
	`56`	`+ # This is hacky, but on terraform plan the data source gives empty strings,`
	`57`	`+ # which fails validation.`
	`58`	`+ username = length(local.artifactory_username) > 0 ? local.artifactory_username : "plan"`
`59`	`59`	`}`
`60`	`60`
`61`	`61`	`resource "coder_agent" "main" {`
`@@ -125,13 +125,13 @@ resource "docker_volume" "home_volume" {`
`125`	`125`	`resource "docker_image" "main" {`
`126`	`126`	`name = "coder-${data.coder_workspace.me.id}"`
`127`	`127`	`build {`
`128`		`- context = "./build"`
	`128`	`+ context = "${path.module}/build"`
`129`	`129`	`build_args = {`
`130`	`130`	`USER = local.workspace_user`
`131`	`131`	`}`
`132`	`132`	`}`
`133`	`133`	`triggers = {`
`134`		`- dir_sha1 = sha1(join("", [for f in fileset(path.module, "build/*") : filesha1(f)]))`
	`134`	`+ dir_sha1 = sha1(join("", [for f in fileset(path.module, "build/*") : filesha1("${path.module}/${f}")]))`
`135`	`135`	`}`
`136`	`136`	`}`
`137`	`137`