Skip to content

Commit 0523c25

Browse files
timothyb89github-actions
timothyb89
authored and
github-actions
committed
Machine ID: Documentation for Bitbucket Pipelines joining
This adds guides and other documentation for the `bitbucket` join method, which allows Machine ID bots to join from Bitbucket Pipelines runs without shared secrets. Follow up to #48724
1 parent 1a7c26f commit 0523c25

File tree

4 files changed

+212
-2
lines changed

4 files changed

+212
-2
lines changed

‎docs/pages/enroll-resources/machine-id/deployment/bitbucket.mdx

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
---
2+
title: Deploying Machine ID on Bitbucket Pipelines
3+
description: How to install and configure Machine ID on Bitbucket Pipelines
4+
---
5+
6+
In this guide, you will configure Machine ID's agent, `tbot`, to run within a
7+
Bitbucket Pipelines workflow. The bot will be configured to use the `bitbucket`
8+
delegated joining method to eliminate the need for long-lived secrets.
9+
10+
## Prerequisites
11+
12+
(!docs/pages/includes/edition-prereqs-tabs.mdx!)
13+
14+
- (!docs/pages/includes/tctl.mdx!)
15+
- A Bitbucket repository you can push to.
16+
17+
## Step 1/4. Determine Bitbucket configuration
18+
19+
Bitbucket joining requires a number of configuration parameters that can be
20+
found in your repository settings. From the Bitbucket repository, navigate to
21+
"Repository settings", then in the sidebar under "Pipelines" select "OpenID
22+
Connect".
23+
24+
From this page, note the following values:
25+
- Identity provider URL (<Var name="identity-provider-url" />)
26+
- Audience (<Var name="audience" />)
27+
- Workspace UUID (<Var name="workspace-uuid" />)
28+
- Repository UUID (<Var name="repository-uuid" />)
29+
30+
## Step 2/4. Create the Machine ID bot
31+
32+
(!docs/pages/includes/machine-id/create-a-bot.mdx!)
33+
34+
## Step 3/4. Create the join token for Bitbucket Pipelines
35+
36+
In order to allow your Pipelines workflow to authenticate with your Teleport
37+
cluster, you'll first need to create a join token. These tokens set out criteria
38+
by which the Auth Server decides whether or not to allow a bot or node to join.
39+
40+
Create a file named `bot-token.yaml`, ensuring that you replace the
41+
`identity_provider_url`, `audience`, `workspace_uuid`, and `repository_uuid`
42+
with the values from Step 1.
43+
44+
```yaml
45+
kind: token
46+
version: v2
47+
metadata:
48+
name: example-bot
49+
spec:
50+
roles: [Bot]
51+
join_method: bitbucket
52+
bot_name: example
53+
bitbucket:
54+
identity_provider_url: <Var name="identity-provider-url" />
55+
audience: <Var name="audience" />
56+
# allow specifies the rules by which the Auth Server determines if `tbot`
57+
# should be allowed to join.
58+
allow:
59+
- workspace_uuid: <Var name="workspace-uuid" />
60+
repository_uuid: <Var name="repository-uuid" />
61+
```
62+
63+
Let's go over the token resource's fields in more detail:
64+
65+
- `metadata.name` defines the name of the token. Note that this value will need
66+
to be used in other parts of the configuration later.
67+
- `spec.bot_name` is the name of the Machine ID bot that this token will grant
68+
access to. Note that this value will need to be used in other parts of the
69+
configuration later.
70+
- `spec.roles` defines which roles that this token will grant access to. The
71+
value of `[Bot]` states that this token grants access to a Machine ID bot.
72+
- `spec.join_method` defines the join method the token is applicable for. Since
73+
this guide only focuses on Bitbucket Pipelines, you will set this to to
74+
`bitbucket`.
75+
- `spec.bitbucket.identity_provider_url` is the identity provider URL shown in
76+
the Bitbucket repository settings, under Pipelines and OpenID Connect.
77+
- `spec.bitbucket.audience` is the audience value shown in the Bitbucket
78+
repository settings, under Pipelines and OpenID connect.
79+
- `spec.bitbucket.allow` is used to set rules for what Bitbucket Pipelines runs
80+
will be able to authenticate by using the token.
81+
82+
Refer to the [token reference](../../../reference/join-methods.mdx#bitbucket-pipelines-bitbucket)
83+
for a full list of valid fields.
84+
85+
Apply this to your Teleport cluster using `tctl`:
86+
87+
```code
88+
$ tctl create -f bot-token.yaml
89+
```
90+
91+
## Step 4/4. Configure a Bitbucket Pipelines workflow
92+
93+
With the bot and join token created, you can now configure a workflow that can
94+
authenticate to Teleport.
95+
96+
This example workflow defines a "custom" pipeline that can be triggered manually
97+
from "Pipelines" or "Branches" views:
98+
99+
```yaml
100+
image: atlassian/default-image:3
101+
102+
pipelines:
103+
custom:
104+
run-tbot:
105+
- step:
106+
oidc: true
107+
script:
108+
# Download and extract Teleport
109+
- wget https://cdn.teleport.dev/teleport-v(=teleport.version=)-linux-amd64-bin.tar.gz
110+
- tar -xvf teleport-v(=teleport.version=)-linux-amd64-bin.tar.gz
111+
112+
# Run `tbot` in identity mode for SSH access
113+
- ./teleport/tbot start identity --destination=./tbot-user --join-method=bitbucket --proxy-server=example.teleport.sh:443 --token=bot-bitbucket --oneshot
114+
115+
# Make use of the generated SSH credentials
116+
- ssh -F ./tbot-user/ssh_config user@node.example.teleport.sh echo "hello world"
117+
```
118+
119+
This example will start `tbot` in identity mode to generate SSH credentials.
120+
Refer to the [`tbot start` documentation](../../../reference/cli/tbot.mdx#tbot-start)
121+
for details on using other modes such as database, application, and Kubernetes
122+
access.
123+
124+
If you're adapting an existing workflow, note these steps:
125+
1. Set `oidc: true` on the step properties so that step will be issued a token
126+
1. Download and extract a `.tar.gz` Teleport build
127+
1. Run `tbot` with `--join-method=bitbucket`, `--token=example-bot` (or
128+
whichever name was configured in Step 3), and `--oneshot`
129+
130+
<Admonition type="warning" title="Sharing credentials between steps">
131+
Note that in Bitbucket Pipelines, outputs cannot be securely shared between
132+
steps as anything stored using `artifacts` will remain downloadable once the CI
133+
run has completed.
134+
135+
Due to this limitation, all operations making use of Teleport credentials should
136+
be performed as part of the same step. If necessary, you can duplicate the
137+
script shown here to download and run `tbot` multiple times in a given run if
138+
credentials are needed in multiple steps.
139+
</Admonition>
140+
141+
## Further steps
142+
143+
- Follow the [access guides](../access-guides/access-guides.mdx) to finish configuring `tbot` for
144+
your environment.
145+
- Read the [configuration reference](../../../reference/machine-id/configuration.mdx) to explore
146+
all the available configuration options.
147+
- For more information about Bitbucket Pipelines itself, read
148+
[their documentation](https://support.atlassian.com/bitbucket-cloud/docs/get-started-with-bitbucket-pipelines/).
149+

‎docs/pages/enroll-resources/machine-id/deployment/deployment.mdx

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,9 +68,10 @@ integration and continuous deployment platform
6868

6969
| Platform | Installation method | Join method |
7070
|-----------------------------------------------------------------------------------------------------|---------------------------------------------------------------|------------------------------------|
71+
| [Bitbucket Pipelines](bitbucket.mdx) | TAR archive | Bitbucket-signed identity document |
7172
| [CircleCI](circleci.mdx) | TAR archive | CircleCI-signed identity document |
7273
| [GitLab](gitlab.mdx) | TAR archive | GitLab-signed identity document |
7374
| [GitHub Actions](github-actions.mdx) | Teleport job available through the GitHub Actions marketplace | GitHub-signed identity document. |
7475
| [Jenkins](jenkins.mdx) | Package manager or TAR archive | Static join token |
7576
| [Spacelift](../../../admin-guides/infrastructure-as-code/terraform-provider/spacelift.mdx) | Docker Image | Spacelift-signed identity document |
76-
| [Terraform Cloud](../../../admin-guides/infrastructure-as-code/terraform-provider/terraform-cloud.mdx) | Teleport Terraform Provider via Teleport's Terraform Registry | Terraform Cloud-signed identity document |
77+
| [Terraform Cloud](../../../admin-guides/infrastructure-as-code/terraform-provider/terraform-cloud.mdx) | Teleport Terraform Provider via Teleport's Terraform Registry | Terraform Cloud-signed identity document |

‎docs/pages/includes/provision-token/bitbucket-spec.mdx

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
```yaml
2+
kind: token
3+
version: v2
4+
metadata:
5+
name: example-bot
6+
spec:
7+
roles: [Bot]
8+
join_method: bitbucket
9+
bot_name: example
10+
bitbucket:
11+
# The URL of the workspace-specific OIDC identity provider. This can be
12+
# found in the repository settings under "Pipelines" and "OpenID Connect".
13+
identity_provider_url: $IDENTITY_PROVIDER_URL
14+
15+
# The audience of the OIDC tokens issued by Bitbucket. This can be found in
16+
# the repository settings under "Pipelines" and "OpenID Connect".
17+
audience: $AUDIENCE
18+
19+
# allow specifies the rules by which the Auth Server determines if `tbot`
20+
# should be allowed to join. All parameters in a given allow entry must
21+
# match for the join attempt to succeed, but many allow rules may be
22+
# provided. One or both of `workspace_uuid` and `repository_uuid` are
23+
# required; all other fields are optional.
24+
allow:
25+
- # The UUID of a workspace whose runs should be allowed to connect. This
26+
# value can be found in the repository settings under "Pipelines" and
27+
# "OpenID Connect". It must be enclosed in braces, i.e. `{...}`. At
28+
# least `workspace_uuid` or `repository_uuid` must be provided.
29+
workspace_uuid: '{WORKSPACE_UUID}'
30+
31+
# The UUID of a repository whose runs should be allowed to connect. This
32+
# value can be found in the repository settings under "Pipelines" and
33+
# "OpenID Connect". It must be enclosed in braces, i.e. `{...}`. At
34+
# least `workspace_uuid` or `repository_uuid` must be provided.
35+
repository_uuid: '{REPOSITORY_UUID}'
36+
37+
# If set, only steps tagged with the deployment environment linked to
38+
# this UUID will be allowed to connect. This value can be found in the
39+
# repository settings under "Pipelines" and "OpenID Connect" when a
40+
# deployment environment is selected from the drop-down menu. It must be
41+
# enclosed in braces, i.e. `{...}`. Optional.
42+
deployment_environment_uuid: '{DEPLOYMENT_ENVIRONMENT_UUID}'
43+
44+
# If set, only workflows running on the named branch will be allowed to
45+
# connect. Optional.
46+
branch_name: "main"
47+
```

‎docs/pages/reference/join-methods.mdx

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -300,7 +300,7 @@ method](#aws-iam-role-iam) or [ephemeral secret tokens](#ephemeral-tokens).
300300

301301
### Azure managed identity: `azure`
302302

303-
The Azure join method is available to any Teleport process running in an
303+
The Azure join method is available to any Teleport process running in an
304304
Azure Virtual Machine. Support for joining a cluster with the Proxy Service
305305
behind a layer 7 load balancer or reverse proxy is available in Teleport 13.0+.
306306

@@ -439,3 +439,16 @@ Support for self-hosted Terraform Enterprise requires Teleport Enterprise.
439439
<Admonition type="note" title="See Also">
440440
- [Run the Teleport Terraform Provider on Terraform Cloud](../admin-guides/infrastructure-as-code/terraform-provider/terraform-cloud.mdx)
441441
</Admonition>
442+
443+
### Bitbucket Pipelines: `bitbucket`
444+
445+
This join method is used to authenticate using Bitbucket's support for OpenID
446+
Connect, and is typically used to allow either Machine ID's `tbot` or the
447+
Teleport Terraform provider to authenticate to Teleport without use of shared
448+
secrets.
449+
450+
(!docs/pages/includes/provision-token/bitbucket-spec.mdx!)
451+
452+
<Admonition type="note" title="See Also">
453+
- [Deploying Machine ID on Bitbucket Pipelines](../enroll-resources/machine-id/deployment/bitbucket.mdx)
454+
</Admonition>

0 commit comments

Comments
 (0)