Skip to content

Commit

Permalink
Add new VCS Agent (multi-arch) to docs
Browse files Browse the repository at this point in the history 
Signed-off-by: peterdeme <snypox@gmail.com>
  • Loading branch information
@peterdeme
peterdeme committed Nov 28, 2023
1 parent 5931acb commit e2c366e
Showing 1 changed file with 43 additions and 36 deletions.
79 changes: 43 additions & 36 deletions docs/concepts/vcs-agent-pools.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,46 +23,20 @@ Give your VCS Agent Pool a name and description, and you're done! A configuratio

![Creation of VCS Agent Pool](../assets/screenshots/Screen Shot 2022-06-21 at 11.29.22 AM.png)

## Download the VCS Agent binary
## Running the VCS Agent

The latest version of the VCS Agent binary can be downloaded from [here](https://downloads.spacelift.io/spacelift-vcs-agent).
### Download the VCS Agent binaries

## Configure and run the VCS Agent

A number of configuration variables is available to customize how your VCS Agent behaves. The ones marked as required are … well … required.

| CLI Flag | Environment Variable | Status | Default Value | Description |
|--------------------------| ------------------------------------------ |------ |---------------|--------------------------------------------------------------------------------------------------------------------------------------|
| `--target-base-endpoint` | `SPACELIFT_VCS_AGENT_TARGET_BASE_ENDPOINT` | Required | | The internal endpoint of your VCS system, including the protocol, as well as port, if applicable. (e.g., `http://169.254.0.10:7990`) |
| `--token` | `SPACELIFT_VCS_AGENT_POOL_TOKEN` | Required | | The token you’ve received from Spacelift during VCS Agent Pool creation |
| `--vendor` | `SPACELIFT_VCS_AGENT_VENDOR` | Required | | The vendor of your VCS system. Currently available options are `gitlab`, `bitbucket_datacenter` and `github_enterprise` |
| `--allowed-projects` | `SPACELIFT_VCS_AGENT_ALLOWED_PROJECTS` | Optional | `.*` | Regexp matching allowed projects for API calls. Projects are in the form: 'group/repository'. |
| `--bugsnag-api-key` | `SPACELIFT_VCS_AGENT_BUGSNAG_API_KEY` | Optional | | Override the Bugsnag API key used for error reporting. |
| `--parallelism` | `SPACELIFT_VCS_AGENT_PARALLELISM` | Optional | `4` | Number of streams to create. Each stream can handle one request simultaneously. |
| `--debug-print-all` | `SPACELIFT_VCS_AGENT_DEBUG_PRINT_ALL` | Optional | `false` | Makes vcs-agent print out all the requests and responses. |
| | `HTTPS_PROXY` | Optional | | Hostname or IP address of the proxy server, including the protocol, as well as port, if applicable. (e.g., `http://10.10.1.1:8888`) |
| | `NO_PROXY` | Optional | | Comma-separated list of host names that shouldn't go through any proxy is set in. |

Congrats! Your VCS Agent should now connect to the Spacelift backend and start handling connections.

![Running the VCS Agent](<../assets/screenshots/image (51).png>)

Within the VCS Agent Pools page, you will be able to see the number of active connections used by your pool.

![VCS Agent Pool Connections](<../assets/screenshots/image (47).png>)

!!! warning
Now whenever you need to specify an endpoint inside of Spacelift which should use your VCS Agent Pool, you should write it this way: `private://my-vcs-agent-pool-name/possible/path`
The latest version of the VCS Agent binaries are avaiable at Spacelift's CDN: [x86_64](https://downloads.spacelift.io/spacelift-vcs-agent-x86_64) (amd64 CPU) and [aarch64](https://downloads.spacelift.io/spacelift-vcs-agent-aarch64) (arm64 CPU).

![](<../assets/screenshots/Screen Shot 2022-06-21 at 11.34.18 AM.png>)

When trying to use this integration, i.e. by opening the Stack creation form, you'll get a detailed log of the requests:
### Run via Docker

![Access Log example](<../assets/screenshots/image (50).png>)
The VCS Agent is also available as a multi-arch (amd64 and arm64) Docker image:

## Run the VCS Agent as a container
- `public.ecr.aws/spacelift/vcs-agent:latest`
- `public.ecr.aws/spacelift/vcs-agent:<version>`

You can run the VCS Agent as a Docker container:
The available versions are listed in the [GitHub Releases](https://github.com/spacelift-io/vcs-agent/releases) page.

```shell
docker run -it --rm -e "SPACELIFT_VCS_AGENT_POOL_TOKEN=<VCS TOKEN>" \
Expand All @@ -71,7 +45,7 @@ docker run -it --rm -e "SPACELIFT_VCS_AGENT_POOL_TOKEN=<VCS TOKEN>" \
public.ecr.aws/spacelift/vcs-agent
```

## Run the VCS Agent inside a Kubernetes Cluster
### Run the VCS Agent inside a Kubernetes Cluster

We have a [VCS Agent Helm Chart](https://github.com/spacelift-io/spacelift-helm-charts){: rel="nofollow"} that you can use to install the VCS Agent on top of your Kubernetes Cluster. After creating a VCS Agent Pool in Spacelift and generating a token, you can add our Helm chart repo and update your local cache using:

Expand All @@ -87,6 +61,39 @@ variables, you can install the chart using the following command:
helm upgrade vcs-agent spacelift/vcs-agent --install --set "credentials.token=$SPACELIFT_VCS_AGENT_POOL_TOKEN,credentials.endpoint=$SPACELIFT_VCS_AGENT_TARGET_BASE_ENDPOINT,credentials.vendor=$SPACELIFT_VCS_AGENT_VENDOR"
```

## Configure and run the VCS Agent

A number of configuration variables is available to customize how your VCS Agent behaves. The ones marked as required are … well … required.

| CLI Flag | Environment Variable | Status | Default Value | Description |
| ------------------------ | ------------------------------------------ | -------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `--target-base-endpoint` | `SPACELIFT_VCS_AGENT_TARGET_BASE_ENDPOINT` | Required | | The internal endpoint of your VCS system, including the protocol, as well as port, if applicable. (e.g., `http://169.254.0.10:7990`) |
| `--token` | `SPACELIFT_VCS_AGENT_POOL_TOKEN` | Required | | The token you’ve received from Spacelift during VCS Agent Pool creation |
| `--vendor` | `SPACELIFT_VCS_AGENT_VENDOR` | Required | | The vendor of your VCS system. Currently available options are `gitlab`, `bitbucket_datacenter` and `github_enterprise` |
| `--allowed-projects` | `SPACELIFT_VCS_AGENT_ALLOWED_PROJECTS` | Optional | `.*` | Regexp matching allowed projects for API calls. Projects are in the form: 'group/repository'. |
| `--bugsnag-api-key` | `SPACELIFT_VCS_AGENT_BUGSNAG_API_KEY` | Optional | | Override the Bugsnag API key used for error reporting. |
| `--parallelism` | `SPACELIFT_VCS_AGENT_PARALLELISM` | Optional | `4` | Number of streams to create. Each stream can handle one request simultaneously. |
| `--debug-print-all` | `SPACELIFT_VCS_AGENT_DEBUG_PRINT_ALL` | Optional | `false` | Makes vcs-agent print out all the requests and responses. |
| | `HTTPS_PROXY` | Optional | | Hostname or IP address of the proxy server, including the protocol, as well as port, if applicable. (e.g., `http://10.10.1.1:8888`) |
| | `NO_PROXY` | Optional | | Comma-separated list of host names that shouldn't go through any proxy is set in. |

Congrats! Your VCS Agent should now connect to the Spacelift backend and start handling connections.

![Running the VCS Agent](<../assets/screenshots/image (51).png>)

Within the VCS Agent Pools page, you will be able to see the number of active connections used by your pool.

![VCS Agent Pool Connections](<../assets/screenshots/image (47).png>)

!!! warning
Now whenever you need to specify an endpoint inside of Spacelift which should use your VCS Agent Pool, you should write it this way: `private://my-vcs-agent-pool-name/possible/path`

![](<../assets/screenshots/Screen Shot 2022-06-21 at 11.34.18 AM.png>)

When trying to use this integration, i.e. by opening the Stack creation form, you'll get a detailed log of the requests:

![Access Log example](<../assets/screenshots/image (50).png>)

### Passing Metadata Tags

When the VCS Agent from a VCS Agent Pool is connecting to the gateway, you can send along some tags that will allow you to uniquely identify the process / machine for the purpose of debugging. Any environment variables using `SPACELIFT_METADATA_` prefix will be passed on. As an example, if you're running Spacelift VCS Agents in EC2, you can do the following just before you execute the VCS Agent binary:
Expand All @@ -97,7 +104,7 @@ export SPACELIFT_METADATA_instance_id=$(ec2-metadata --instance-id | cut -d ' '

Doing so will set your EC2 instance ID as _instance_id_ tag in your VCS Agent connections.

### Private Workers
## Private Workers

VCS agents are only supported when using private worker pools. Because your source code is downloaded directly by Spacelift workers, you need to configure your workers to know how to reach your VCS instance. Information on how to do this is provided on the [worker pools](worker-pools.md#vcs-agents) page.

Expand Down

0 comments on commit e2c366e

Please sign in to comment.