Skip to content

Commit

Permalink
Update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@FooBarWidget
FooBarWidget committed Aug 16, 2024
1 parent add32c0 commit 58b3ac3
Show file tree
Hide file tree
Showing 13 changed files with 114 additions and 190 deletions.
10 changes: 5 additions & 5 deletions .github/ISSUE_TEMPLATE/clear_ci_artifacts.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,14 @@
name: Clear CI artifacts
about: Request clearing of corrupt CI artifacts
title: Clear corrupt CI artifacts for server-edition/<CI RUN NUMBER>
labels: ''
assignees: ''
labels: ""
assignees: ""
---

Please clear the CI artifacts for the following CI run:

- Project: server-edition
- CI run number: (please fill in; don't forget to update the title too)
- Project: server-edition
- CI run number: (please fill in; don't forget to update the title too)

<!--
You can find out the CI run number as follows:
Expand All @@ -25,4 +25,4 @@ You can find out the CI run number as follows:

## Instructions for infra team members

See [this guide](https://github.com/fullstaq-labs/fullstaq-ruby-infra/blob/main/docs/clearing-ci-artifacts.md).
See [this guide](https://github.com/fullstaq-ruby/infra/blob/main/docs/clearing-ci-artifacts.md).
26 changes: 13 additions & 13 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,26 +1,26 @@
# Contribution guide

> You are reading the contribution guide for the **Infrastructure Team**. Interested in contributing to other parts of Fullstaq Ruby? Check the [Fullstaq Ruby Umbrella contribution guide](https://github.com/fullstaq-labs/fullstaq-ruby-umbrella/blob/main/CONTRIBUTING.md).
> You are reading the contribution guide for the **Infrastructure Team**. Interested in contributing to other parts of Fullstaq Ruby? Check the [Fullstaq Ruby Umbrella contribution guide](https://github.com/fullstaq-ruby/umbrella/blob/main/CONTRIBUTING.md).
Thanks for considering to contribute! 😀 We welcome all contributions, no matter who you are, and no matter whether it's big or small (see also our [Code of Conduct](CODE_OF_CONDUCT.md)). With this guide, we aim to make contributing as clear and easy as possible.

## What counts as a contribution?

Anything that helps improving the infrastructure, whether directly (through a pull request) or indirectly (by engaging with us) counts as a contribution. Here's a non-exhaustive list:

* Reporting an infrastructure issue.
* Triaging issues: determining whether an issue report is clear enough, whether the issue still persists, and whether it is reproducible.
* Updating documentation.
* Proposing an improvement.
* Sending a pull request.
* Reviewing someone else's pull request.
- Reporting an infrastructure issue.
- Triaging issues: determining whether an issue report is clear enough, whether the issue still persists, and whether it is reproducible.
- Updating documentation.
- Proposing an improvement.
- Sending a pull request.
- Reviewing someone else's pull request.

## Not sure how to get started?

Have a look at our [issue tracker](https://github.com/fullstaq-labs/fullstaq-ruby-infra/issues). Issues with the following labels are good starting points:
Have a look at our [issue tracker](https://github.com/fullstaq-ruby/infra/issues). Issues with the following labels are good starting points:

* "good first issue" if you're looking for something easy.
* "help wanted" if you're in for a challenge, or if you want to help with a high-impact issue.
- "good first issue" if you're looking for something easy.
- "help wanted" if you're in for a challenge, or if you want to help with a high-impact issue.

## Required development tools

Expand All @@ -40,9 +40,9 @@ To learn more about what it means to be a team member, see [Responsibilities & e

Because joining the team means gaining access to protected resources, trust is essential. We judge trustworthiness through the following manners:

* Having an established relationship with either the Fullstaq Ruby project, or the wider Ruby community. The longer the better.
* A contractual relationship (such as employment) with [Fullstaq B.V.](https://fullstaq.com/). Contractual relationships carry legal weight and provide greater likelihood of a stable trust relationship; at a minimum they establish strong legal accountability.
- Having an established relationship with either the Fullstaq Ruby project, or the wider Ruby community. The longer the better.
- A contractual relationship (such as employment) with [Fullstaq B.V.](https://fullstaq.com/). Contractual relationships carry legal weight and provide greater likelihood of a stable trust relationship; at a minimum they establish strong legal accountability.

### Apply

If you wish to join, please [apply by submitting an issue](https://github.com/fullstaq-labs/fullstaq-ruby-infra/issues/new?template=apply_join_team.md).
If you wish to join, please [apply by submitting an issue](https://github.com/fullstaq-ruby/infra/issues/new?template=apply_join_team.md).
8 changes: 4 additions & 4 deletions docs/clearing-ci-artifacts.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,12 @@ Developers request the clearing of CI artifacts via the issue tracker, using [th

Here's how you should process such a support request:

1. Go to the Google Cloud Storage bucket named [fullstaq-ruby-server-edition-ci-artifacts](https://console.cloud.google.com/storage/browser/fullstaq-ruby-server-edition-ci-artifacts?project=fullstaq-ruby) in the `fullstaq-ruby` project.
2. Delete the folder whose name equals the reported CI run number.
3. Close the issue with the following canned response:
1. Go to the Google Cloud Storage bucket named [fullstaq-ruby-server-edition-ci-artifacts](https://console.cloud.google.com/storage/browser/fullstaq-ruby-server-edition-ci-artifacts?project=fullstaq-ruby) in the `fullstaq-ruby` project.
2. Delete the folder whose name equals the reported CI run number.
3. Close the issue with the following canned response:

> The artifacts have been cleared. Please re-run the CI job whenever convenient.
## See also

* [Troubleshooting corrupt CI/CD artifacts — Server Edition development handbook](https://github.com/fullstaq-labs/fullstaq-ruby-server-edition/blob/main/dev-handbook/troubleshooting-corrupt-ci-cd-artifacts.md)
- [Troubleshooting corrupt CI/CD artifacts — Server Edition development handbook](https://github.com/fullstaq-ruby/server-edition/blob/main/dev-handbook/troubleshooting-corrupt-ci-cd-artifacts.md)
105 changes: 19 additions & 86 deletions docs/infrastructure-bootstrapping.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -124,102 +124,35 @@ ansible-playbook -i hosts.ini -v main.yml
cd ..
```

## Step 11: Populate Github Actions secrets
## Step 11: Populate Github Actions secrets and variables

Terraform has created two Google Cloud service accounts and one Azure storage account. Their corresponding private keys and connection string must be installed as Github Actions secrets in the corresponding Github projects.
In the [fullstaq-ruby/server-edition](https://github.com/fullstaq-ruby/server-edition/settings/secrets) repo, create the following environments:

- _Infrastructure CI Bot_: used by the Infrastructure team's CI/CD systems.
- test
- deploy

Fetch the private key (in JSON format, base64-encoded) from the Terraform state and decode it:
Create these environment-specific secrets:

```bash
pushd terraform && terraform show -json | jq -r '.values.root_module.resources[] | select(.name == "infra-ci-bot-sa-key") | .values.private_key' | base64 --decode && popd
```
In the [fullstaq-ruby/infra](https://github.com/fullstaq-ruby/infra/settings/secrets) repo, paste this value into a secret named `GCLOUD_KEY`.
- _Server Edition CI Bot_: used by Server Edition's developers' CI/CD systems to publish artifacts to the `fullstaq-ruby` Google Cloud project, and to cache to the `fsruby2seredci1` Azure storage account.
- Fetch the Google Cloud service account private key (in JSON format, base64-encoded) from the Terraform state:
```bash
pushd terraform && terraform show -json | jq -r '.values.root_module.resources[] | select(.name == "server-edition-ci-bot-sa-key") | .values.private_key' && popd
```
In the [fullstaq-ruby/server-edition](https://github.com/fullstaq-ruby/server-edition/settings/secrets) repo, paste this value into a secret named `GCLOUD_KEY`.
- Fetch the Azure storage account connection string from the Terraform state:
```bash
pushd terraform && terraform show -json | jq -r '.values.root_module.resources[] | select(.address == "azurerm_storage_account.server-edition-ci") | .values.primary_blob_connection_string' && popd
```
In the [fullstaq-ruby/server-edition](https://github.com/fullstaq-ruby/server-edition/settings/secrets) repo, paste this value into a secret named `AZURE_CI1_STORAGE_CONNECTION_STRING`.
## Step 12: Register a Github bot account
- `AZURE_CI2_STORAGE_CONNECTION_STRING` ('test' environment):

### Create an email inbox for the Github bot account
Fetch the value from the Terraform state:

In the Fullstaq G Suite admin console, create a new group:
- Name: Fullstaq Ruby CI bot
- Email: fullstaq-ruby-ci-bot@fullstaq.com
Go to its [Advanced Settings](https://groups.google.com/a/fullstaq.com/g/fullstaq-ruby-ci-bot/settings) and ensure the following settings:
- General:
- Who can see this group: Organisation members
- Who can join this group: Invited users only
- Who can view conversations: Group managers
- Who can post: Anyone on the web
- Who can view members: Group managers
- Member privacy:
- Identification required for new members: Display profile name only
- Who can view the member's email addresses: Group managers
- Posting policies:
- Conversation history: on
- Who can moderate content: Group managers
- Who can moderate metadata: Group managers
- Who can post as the group: Group owners
- Message moderation: No moderation
- New member restrictions: No posting restriction for new members
- Member moderation
- Who can manage members: Group managers
- Permission to modify custom roles: Group owners

### Register the Github bot account

Account details:

- Username: fullstaq-ruby-ci-bot
- Email: fullstaq-ruby-ci-bot@fullstaq.com

Store the password in Secret Manager:

1. Go to the `fullstaq-ruby-hisec` Google Cloud project.
2. Go to Security ➜ Secret Manager.
3. Create a secret with the name `fullstaq-ruby-ci-bot-password` and insert the password.

### Personal access token

Create a personal access token:

- Note: Server Edition CI
- Scope: repo

Store this token in Secret Manager:

1. Go to the `fullstaq-ruby-hisec` Google Cloud project.
2. Go to Security ➜ Secret Manager.
3. Create a secret with the name `fullstaq-ruby-ci-bot-server-edition-pat` and insert the personal access token.
```bash
pushd terraform >/dev/null && terraform show -json | jq -r '.values.root_module.resources[] | select(.address == "azurerm_storage_account.server-edition-ci") | .values.primary_blob_connection_string'; popd >/dev/null
```

### Install Github Actions secret
Create these repository variables:

In the [fullstaq-ruby-server-edition](https://github.com/fullstaq-labs/fullstaq-ruby-server-edition/settings/secrets) repo, create a Github Actions secret named `WORKFLOW_DISPATCH_TOKEN`. Set it to the personal access token.
- `AZURE_SUBSCRIPTION_ID`: see corresponding variable in terraform/variables.tf
- `AZURE_TENANT_ID`: see corresponding variable in terraform/variables.tf
- `GCLOUD_PROJECT_ID`: see corresponding variable in terraform/variables.tf
- `GCLOUD_PROJECT_NUM`: lookup the project number in Google Cloud.
- `CI_ARTIFACTS_BUCKET`: fetch using `pushd terraform >/dev/null && terraform show -json | jq -r '.values.root_module.resources[] | select(.address == "google_storage_bucket.server-edition-ci-artifacts") | .values.name'; popd >/dev/null`

### Grant access to key repositories
Create these environment-specific variables:

In the [fullstaq-ruby-server-edition](https://github.com/fullstaq-labs/fullstaq-ruby-server-edition/settings/access) repo, add fullstaq-ruby-ci-bot as a collaborator. Grant the "Write" access.
- `AZURE_CLIENT_ID` ('test' environment): fetch using `pushd terraform-hisec >/dev/null && terraform show -json | jq -r '.values.root_module.resources[] | select(.address == "azuread_application.server-edition-github-ci-test") | .values.application_id'; popd >/dev/null`
- `AZURE_CLIENT_ID` ('deploy' environment): fetch using `pushd terraform-hisec >/dev/null && terraform show -json | jq -r '.values.root_module.resources[] | select(.address == "azuread_application.server-edition-github-ci-deploy") | .values.application_id'; popd >/dev/null`

## Step 13: Onboard everybody

Expand Down
Loading

0 comments on commit 58b3ac3

Please sign in to comment.