Skip to content

Commit 03f5a93

Browse files
stirbymatifali
stirby
authored and
matifali
committed
migrated guides to tutorials
1 parent 90d92e1 commit 03f5a93

12 files changed

+1270
-6
lines changed

‎docs/manifest.json

Lines changed: 45 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -282,11 +282,6 @@
282282
"path": "./tutorials/README.md",
283283
"icon_path": "./images/icons/generic.svg",
284284
"children": [
285-
{
286-
"title": "Workspaces",
287-
"description": "Create, configure, and connect to Coder workspaces",
288-
"path": "./tutorials/workspaces/README.md"
289-
},
290285
{
291286
"title": "Write a Template from Scratch",
292287
"description": "Learn how to author Coder templates",
@@ -296,6 +291,51 @@
296291
"title": "Image Management",
297292
"description": "Learn about image management with Coder",
298293
"path": "./tutorials/image-management.md"
294+
},
295+
{
296+
"title": "Generate a Support Bundle",
297+
"description": "Generate and upload a Support Bundle to Coder Support",
298+
"path": "./tutorials/support-bundle.md"
299+
},
300+
{
301+
"title": "Configuring Okta",
302+
"description": "Custom claims/scopes with Okta for group/role sync",
303+
"path": "./tutorials/configuring-okta.md"
304+
},
305+
{
306+
"title": "Google to AWS Federation",
307+
"description": "Federating a Google Cloud service account to AWS",
308+
"path": "./tutorials/gcp-to-aws.md"
309+
},
310+
{
311+
"title": "JFrog Artifactory Integration",
312+
"description": "Integrate Coder with JFrog Artifactory",
313+
"path": "./tutorials/artifactory-integration.md"
314+
},
315+
{
316+
"title": "Island Secure Browser Integration",
317+
"description": "Integrate Coder with Island's Secure Browser",
318+
"path": "./tutorials/island-integration.md"
319+
},
320+
{
321+
"title": "Template ImagePullSecrets",
322+
"description": "Creating ImagePullSecrets for private registries",
323+
"path": "./tutorials/image-pull-secret.md"
324+
},
325+
{
326+
"title": "Postgres SSL",
327+
"description": "Configure Coder to connect to Postgres over SSL",
328+
"path": "./tutorials/postgres-ssl.md"
329+
},
330+
{
331+
"title": "Azure Federation",
332+
"description": "Federating Coder to Azure",
333+
"path": "./tutorials/azure-federation.md"
334+
},
335+
{
336+
"title": "Scanning Coder Workspaces with JFrog Xray",
337+
"description": "Integrate Coder with JFrog Xray",
338+
"path": "./tutorials/xray-integration.md"
299339
}
300340
]
301341
},

‎docs/tutorials/README.md

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,10 @@
1-
TODO: Bing bong tutorials
1+
# Tutorials
2+
3+
Here you can find a list of employee-written tutorials on Coder for OSS and
4+
Enterprise. These are hosted on our
5+
[Github](https://github.com/coder/coder/) where you can leave feedback or
6+
request new topics to be covered.
7+
8+
<children>
9+
This page is rendered on https://coder.com/docs/v2/latest/guides. Refer to the other documents in the `guides/` directory for specific employee-written guides.
10+
</children>

‎docs/tutorials/artifactory-integration.md

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# JFrog Artifactory Integration
2+
3+
<div>
4+
<a href="https://github.com/matifali" style="text-decoration: none; color: inherit;">
5+
<span style="vertical-align:middle;">M Atif Ali</span>
6+
<img src="https://github.com/matifali.png" width="24px" height="24px" style="vertical-align:middle; margin: 0px;"/>
7+
</a>
8+
</div>
9+
January 24, 2024
10+
11+
---
12+
13+
Use Coder and JFrog Artifactory together to secure your development environments
14+
without disturbing your developers' existing workflows.
15+
16+
This guide will demonstrate how to use JFrog Artifactory as a package registry
17+
within a workspace.
18+
19+
## Requirements
20+
21+
- A JFrog Artifactory instance
22+
- 1:1 mapping of users in Coder to users in Artifactory by email address or
23+
username
24+
- Repositories configured in Artifactory for each package manager you want to
25+
use
26+
27+
## Provisioner Authentication
28+
29+
The most straight-forward way to authenticate your template with Artifactory is
30+
by using our official Coder [modules](https://registry.coder.com). We publish
31+
two type of modules that automate the JFrog Artifactory and Coder integration.
32+
33+
1. [JFrog-OAuth](https://registry.coder.com/modules/jfrog-oauth)
34+
2. [JFrog-Token](https://registry.coder.com/modules/jfrog-token)
35+
36+
### JFrog-OAuth
37+
38+
This module is usable by JFrog self-hosted (on-premises) Artifactory as it
39+
requires configuring a custom integration. This integration benefits from
40+
Coder's [external-auth](https://coder.com/docs/v2/latest/admin/external-auth)
41+
feature and allows each user to authenticate with Artifactory using an OAuth
42+
flow and issues user-scoped tokens to each user.
43+
44+
To set this up, follow these steps:
45+
46+
1. Modify your Helm chart `values.yaml` for JFrog Artifactory to add,
47+
48+
```yaml
49+
artifactory:
50+
enabled: true
51+
frontend:
52+
extraEnvironmentVariables:
53+
- name: JF_FRONTEND_FEATURETOGGLER_ACCESSINTEGRATION
54+
value: "true"
55+
access:
56+
accessConfig:
57+
integrations-enabled: true
58+
integration-templates:
59+
- id: "1"
60+
name: "CODER"
61+
redirect-uri: "https://CODER_URL/external-auth/jfrog/callback"
62+
scope: "applied-permissions/user"
63+
```
64+
65+
> Note Replace `CODER_URL` with your Coder deployment URL, e.g.,
66+
> <coder.example.com>
67+
68+
2. Create a new Application Integration by going to
69+
<https://JFROG_URL/ui/admin/configuration/integrations/new> and select the
70+
Application Type as the integration you created in step 1.
71+
72+
![JFrog Platform new integration](../images/guides/artifactory-integration/jfrog-oauth-app.png)
73+
74+
3. Add a new
75+
[external authentication](https://coder.com/docs/v2/latest/admin/external-auth)
76+
to Coder by setting these env variables,
77+
78+
```env
79+
# JFrog Artifactory External Auth
80+
CODER_EXTERNAL_AUTH_1_ID="jfrog"
81+
CODER_EXTERNAL_AUTH_1_TYPE="jfrog"
82+
CODER_EXTERNAL_AUTH_1_CLIENT_ID="YYYYYYYYYYYYYYY"
83+
CODER_EXTERNAL_AUTH_1_CLIENT_SECRET="XXXXXXXXXXXXXXXXXXX"
84+
CODER_EXTERNAL_AUTH_1_DISPLAY_NAME="JFrog Artifactory"
85+
CODER_EXTERNAL_AUTH_1_DISPLAY_ICON="/icon/jfrog.svg"
86+
CODER_EXTERNAL_AUTH_1_AUTH_URL="https://JFROG_URL/ui/authorization"
87+
CODER_EXTERNAL_AUTH_1_SCOPES="applied-permissions/user"
88+
```
89+
90+
> Note Replace `JFROG_URL` with your JFrog Artifactory base URL, e.g.,
91+
> <example.jfrog.io>
92+
93+
4. Create or edit a Coder template and use the
94+
[JFrog-OAuth](https://registry.coder.com/modules/jfrog-oauth) module to
95+
configure the integration.
96+
97+
```hcl
98+
module "jfrog" {
99+
source = "registry.coder.com/modules/jfrog-oauth/coder"
100+
version = "1.0.0"
101+
agent_id = coder_agent.example.id
102+
jfrog_url = "https://jfrog.example.com"
103+
configure_code_server = true # this depends on the code-server
104+
username_field = "username" # If you are using GitHub to login to both Coder and Artifactory, use username_field = "username"
105+
package_managers = {
106+
"npm": "npm",
107+
"go": "go",
108+
"pypi": "pypi"
109+
}
110+
}
111+
```
112+
113+
### JFrog-Token
114+
115+
This module makes use of the
116+
[Artifactory terraform provider](https://registry.terraform.io/providers/jfrog/artifactory/latest/docs)
117+
and an admin-scoped token to create user-scoped tokens for each user by matching
118+
their Coder email or username with Artifactory. This can be used for both SaaS
119+
and self-hosted(on-premises) Artifactory instances.
120+
121+
To set this up, follow these steps:
122+
123+
1. Get a JFrog access token from your Artifactory instance. The token must be an
124+
[admin token](https://registry.terraform.io/providers/jfrog/artifactory/latest/docs#access-token)
125+
with scope `applied-permissions/admin`.
126+
2. Create or edit a Coder template and use the
127+
[JFrog-Token](https://registry.coder.com/modules/jfrog-token) module to
128+
configure the integration and pass the admin token. It is recommended to
129+
store the token in a sensitive terraform variable to prevent it from being
130+
displayed in plain text in the terraform state.
131+
132+
```hcl
133+
variable "artifactory_access_token" {
134+
type = string
135+
sensitive = true
136+
}
137+
138+
module "jfrog" {
139+
source = "registry.coder.com/modules/jfrog-token/coder"
140+
version = "1.0.0"
141+
agent_id = coder_agent.example.id
142+
jfrog_url = "https://example.jfrog.io"
143+
configure_code_server = true # this depends on the code-server
144+
artifactory_access_token = var.artifactory_access_token
145+
package_managers = {
146+
"npm": "npm",
147+
"go": "go",
148+
"pypi": "pypi"
149+
}
150+
}
151+
```
152+
153+
<blockquote class="info">
154+
The admin-level access token is used to provision user tokens and is never exposed to
155+
developers or stored in workspaces.
156+
</blockquote>
157+
158+
If you do not want to use the official modules, you can check example template
159+
that uses Docker as the underlying compute
160+
[here](https://github.com/coder/coder/tree/main/examples/jfrog/docker). The same
161+
concepts apply to all compute types.
162+
163+
## Offline Deployments
164+
165+
See the [offline deployments](../templates/modules.md#offline-installations)
166+
section for instructions on how to use coder-modules in an offline environment
167+
with Artifactory.
168+
169+
## More reading
170+
171+
- See the full example template
172+
[here](https://github.com/coder/coder/tree/main/examples/jfrog/docker).
173+
- To serve extensions from your own VS Code Marketplace, check out
174+
[code-marketplace](https://github.com/coder/code-marketplace#artifactory-storage).
175+
- To store templates in Artifactory, check out our
176+
[Artifactory modules](../templates/modules.md#artifactory) docs.

‎docs/tutorials/azure-federation.md

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Federating Coder's control plane to Azure
2+
3+
<div>
4+
<a href="https://github.com/ericpaulsen" style="text-decoration: none; color: inherit;">
5+
<span style="vertical-align:middle;">Eric Paulsen</span>
6+
<img src="https://github.com/ericpaulsen.png" width="24px" height="24px" style="vertical-align:middle; margin: 0px;"/>
7+
</a>
8+
</div>
9+
January 26, 2024
10+
11+
---
12+
13+
This guide will walkthrough how to authenticate a Coder Provisioner to Microsoft
14+
Azure, using a Service Principal with a client certificate. You can use this
15+
guide for authenticating Coder to Azure, regardless of where Coder is run,
16+
either on-premise or in a non-Azure cloud. This method is one of several
17+
[recommended by Terraform](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs#authenticating-to-azure).
18+
19+
## Step 1: Generate Client Certificate & PKCS bundle
20+
21+
We'll need to create the certificate Coder will use for authentication. Run the
22+
below command to generate a private key and self-signed certificate:
23+
24+
```console
25+
openssl req -subj '/CN=myclientcertificate/O=MyCompany, Inc./ST=CA/C=US' \
26+
-new -newkey rsa:4096 -sha256 -days 730 -nodes -x509 -keyout client.key -out client.crt
27+
```
28+
29+
Next, generate a `.pfx` file to be used by Coder's Provisioner to authenticate
30+
the AzureRM provider:
31+
32+
```console
33+
openssl pkcs12 -export -password pass:"Pa55w0rd123" -out client.pfx -inkey client.key -in client.crt
34+
```
35+
36+
## Step 2: Create Azure Application & Service Principal
37+
38+
Navigate to the Azure portal, and into the Microsoft Entra ID section. Select
39+
the App Registration blade, and register a new application. Fill in the
40+
following fields:
41+
42+
- **Name**: this is a friendly identifier and can be anything (e.g. "Coder")
43+
- **Supported Account Types**: - set to "Accounts in this organizational
44+
directory only (single-tenant)"
45+
46+
The **Redirect URI** field does not need to be set in this case. Take note of
47+
the `Application (client) ID` and `Directory (tenant) ID` values, which will be
48+
used by Coder.
49+
50+
## Step 3: Assign Client Certificate to the Azure Application
51+
52+
To upload the certificate we created in Step 1, select **Certificates &
53+
secrets** on the left-hand side, and select **Upload Certificate**. Upload the
54+
public key file, which is `service-principal.crt` from the example above.
55+
56+
## Step 4: Set Permissions on the Service Principal
57+
58+
Now that the Application is created in Microsoft Entra ID, we need to assign
59+
permissions to the Service Principal so it can provision Azure resources for
60+
Coder users. Navigate to the Subscriptions blade in the Azure Portal, select the
61+
**Subscription > Access Control (IAM) > Add > Add role assignment**.
62+
63+
Set the **Role** that grants the appropriate permissions to create the Azure
64+
resources you need for your Coder workspaces. `Contributor` will provide
65+
Read/Write on all Subscription resources. For more information on the available
66+
roles, see the
67+
[Microsoft documentation](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles).
68+
69+
## Step 5: Configure Coder to use the Client Certificate
70+
71+
Now that the client certificate is uploaded to Azure, we need to mount the
72+
certificate files into the Coder deployment. If running Coder on Kubernetes, you
73+
will need to create the `.pfx` file as a Kubernetes secret, and mount it into
74+
the Helm chart.
75+
76+
Run the below command to create the secret:
77+
78+
```console
79+
kubectl create secret generic -n coder azure-client-cert-secret --from-file=client.pfx=/path/to/your/client.pfx
80+
```
81+
82+
In addition, create secrets for each of the following values from your Azure
83+
Application:
84+
85+
- Client ID
86+
- Tenant ID
87+
- Subscription ID
88+
- Certificate password
89+
90+
Next, set the following values in Coder's Helm chart:
91+
92+
```yaml
93+
coder:
94+
env:
95+
- name: ARM_CLIENT_ID
96+
valueFrom:
97+
secretKeyRef:
98+
key: id
99+
name: arm-client-id
100+
- name: ARM_CLIENT_CERTIFICATE_PATH
101+
value: /home/coder/az/
102+
- name: ARM_CLIENT_CERTIFICATE_PASSWORD
103+
valueFrom:
104+
secretKeyRef:
105+
key: password
106+
name: arm-client-cert-password
107+
- name: ARM_TENANT_ID
108+
valueFrom:
109+
secretKeyRef:
110+
key: id
111+
name: arm-tenant-id
112+
- name: ARM_SUBSCRIPTION_ID
113+
valueFrom:
114+
secretKeyRef:
115+
key: id
116+
name: arm-subscription-id
117+
volumes:
118+
- name: "azure-client-cert"
119+
secret:
120+
secretName: "azure-client-cert-secret"
121+
volumeMounts:
122+
- name: "azure-client-cert"
123+
mountPath: "/home/coder/az/"
124+
readOnly: true
125+
```
126+
127+
Upgrade the Coder deployment using the following `helm` command:
128+
129+
```console
130+
helm upgrade coder coder-v2/coder -n coder -f values.yaml
131+
```

0 commit comments

Comments
 (0)