Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

fix: Philips Labs Steps Formatting #675

Merged
merged 6 commits into from
Aug 30, 2024
Merged

fix: Philips Labs Steps Formatting #675

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
f904964
Update webhook setup instructions in philips-labs-github-runners
milldr Aug 28, 2024
334eeec
Update docs/layers/github-actions/philips-labs-github-runners.mdx
milldr Aug 28, 2024
49983e8
Merge branch 'master' into fix/philips-labs-steps
milldr Aug 29, 2024
a95e6a0
refactor philips labs docs
milldr Aug 29, 2024
26a8226
upload workflow names
milldr Aug 29, 2024
c523aee
refactor philips labs docs
milldr Aug 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/layers/github-actions/eks-github-actions-controller.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ In order to deploy Self-Hosted GitHub Runners on EKS, follow the steps outlined
<Note title="Tip">
The first three steps before are all included in the following workflow:

<AtmosWorkflow workflow="deploy/github-runners" fileName="github" />
<AtmosWorkflow workflow="deploy/arc-github-runners" fileName="github" />
</Note>

<Step>
Expand Down
183 changes: 84 additions & 99 deletions docs/layers/github-actions/philips-labs-github-runners.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,16 @@
title: Philips Labs GitHub Action Runners
sidebar_label: Philips Labs Action Runners
---
import Intro from '@site/src/components/Intro';
import KeyPoints from '@site/src/components/KeyPoints';
import AtmosWorkflow from '@site/src/components/AtmosWorkflow';
import Steps from '@site/src/components/Steps';
import Step from '@site/src/components/Step';
import StepNumber from '@site/src/components/StepNumber';

import Intro from "@site/src/components/Intro";
import KeyPoints from "@site/src/components/KeyPoints";
import AtmosWorkflow from "@site/src/components/AtmosWorkflow";
import Steps from "@site/src/components/Steps";
import Step from "@site/src/components/Step";
import StepNumber from "@site/src/components/StepNumber";
import TaskList from "@site/src/components/TaskList";
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

<Intro>
If we are not deploying EKS, it's not worth the additional effort to set up Self-Hosted runners on EKS. Instead, we
Expand All @@ -18,13 +22,13 @@ import StepNumber from '@site/src/components/StepNumber';

## Quick Start

| Steps | Actions | Calling Workflow |
| :------------------------------------------- | :------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| 1. Generate GitHub App Private Key | Set SSM Param `"/pl-github-runners/key"` to App private Key base64 encoded | `atmos workflow deploy/pl-github-runners -f github` |
| 2. Note GitHub ID | Set SSM Param `"/pl-github-runners/id"` to the GitHub App ID | `atmos workflow deploy/pl-github-runners -f github` |
| 3. Deploy GitHub OIDC Provider | Deploy GitHub OIDC to every needed account | `atmos workflow deploy/github-oidc-provider -f github` |
| 4. Deploy GitHub Runners | Deploy the GitHub runners | `atmos workflow deploy/pl-github-runners -f github` |
| 5. Update Webhook (if changed or redeployed) | Update the GitHub App Webhook | (if `enable_update_github_app_webhook: true`) `atmos workflow deploy/pl-github-runners -f github`. Otherwise Manual |
| Steps | Actions |
| :------------------------------------------------- | :-------------------------------------------------------------------------------------- |
| 1. Create GitHub App | ClickOps |
| 2. Upload GitHub App ID and Private Key to AWS SSM | Set SSM Param `"/pl-github-runners/id"` and `"/pl-github-runners/key"` (base64 encoded) |
| 3. Deploy GitHub OIDC Provider | Deploy GitHub OIDC to every needed account |
| 4. Deploy GitHub Runners | `atmos terraform deploy philips-labs-github-runners -s core-use1-auto` |
| 5. Update Webhook (if changed or redeployed) | ClickOps |

## Deploy

Expand All @@ -35,9 +39,20 @@ hand the setup back to Cloud Posse. Then Cloud Posse can deploy the component an
customer will then need to add the webhook to the GitHub App and ensure the App is installed to all relevant GitHub
repositories.

Follow the guide with the upstream module, [philips-labs/terraform-aws-github-runner](https://github.com/philips-labs/terraform-aws-github-runner#setup-github-app-part-1), or follow the steps below.
Follow the guide with the upstream module,
[philips-labs/terraform-aws-github-runner](https://github.com/philips-labs/terraform-aws-github-runner#setup-github-app-part-1),
or follow the steps below.

<Steps>
<Step>
### <StepNumber/> Vendor Components

Vendor in the necessary components with the following workflow:

<AtmosWorkflow workflow="vendor/philips-labs" fileName="github" />

</Step>

<Step>
### <StepNumber/> Create the GitHub App

Expand All @@ -53,33 +68,41 @@ Follow the guide with the upstream module, [philips-labs/terraform-aws-github-ru
1. Choose a name
1. Choose a website (mandatory, not required for the module).
1. Disable the webhook for now (we will configure this later or create an alternative webhook).
1. Add the following permission:
```diff
# Required Permissions for Repository Runners:
## Permissions for all runners:
### Repository:
+ Actions: Read-only (check for queued jobs)
+ Checks: Read-only (receive events for new builds)
+ Metadata: Read-only (default/required)

## Permissions for repository-level runners only:
### Repository:
+ Administration: Read & write (to register runner)

## Permissions for organization-level runners only:
### Organization
+ Self-hosted runners: Read & write (to register runner)
```
1. Add the following permission for your chosen runner scope:

<Tabs queryString="runners">
<TabItem value="repository" label="Repository-Scoped Runners">
#### Repository Permissions
<TaskList>
- Actions: Read-only (check for queued jobs)
- Checks: Read-only (receive events for new builds)
- Metadata: Read-only (default/required)
- Administration: Read & write (to register runner)
</TaskList>
</TabItem>

<TabItem value="organization" label="Organization-Scoped Runners">
#### Repository Permissions
<TaskList>
- Actions: Read-only (check for queued jobs)
- Checks: Read-only (receive events for new builds)
- Metadata: Read-only (default/required)
</TaskList>
#### Organization Permissions
<TaskList>
- Self-hosted runners: Read & write (to register runner)
</TaskList>
</TabItem>
</Tabs>

1. Generate a Private Key
1. If you are working with Cloud Posse, upload this Private Key and GitHub App ID to 1Password and inform Cloud Posse. Otherwise, continue to the next step.
</Steps>

If you are working with Cloud Posse, upload this Private Key and GitHub App ID to 1Password and inform Cloud Posse.
Otherwise, continue with the component deployment in `core-use1-auto`.
</Step>

<Step>
### <StepNumber/> Deploy the `philips-labs-github-runner` Component
### <StepNumber/> Upload AWS SSM Parameters

:::tip

Expand All @@ -88,30 +111,36 @@ Follow the guide with the upstream module, [philips-labs/terraform-aws-github-ru

:::

Run the `deploy/pl-github-runners` workflow with `atmos` to write the GitHub App information to the `core-use1-auto`
SSM account and deploy the component.

<AtmosWorkflow workflow="deploy/pl-github-runners" fileName="github" />

This is the same as the following steps:
Now that the GitHub App has been created, upload the Private Key and GitHub App ID to AWS SSM Parameter Store in `core-use1-auto` (or your chosen region).

<Steps>
1. Upload the PEM file key to the specified ssm path, `/pl-github-runners/key`, in `core-use1-auto` as a base64
encoded string.
1. Upload the PEM file key to the specified ssm path, `/pl-github-runners/key`, in `core-use1-auto` as a base64 encoded string.
2. Upload the GitHub App ID to the specified ssm path, `/pl-github-runners/id`, in `core-use1-auto`.
3. Deploy the `philips-labs-github-runners` component to `core-use1-auto`. Run this with the following:
</Steps>

```console
atmos terraform apply philips-labs-github-runners -s core-use1-auto
```
Or run the `upload/pl-secrets` workflow with `atmos` to write the GitHub App information to the `core-use1-auto` SSM account and deploy the component.

Once the component is deployed, save the webhook URL and secret in 1Password. The endpoint can be found with the
following:
<AtmosWorkflow workflow="upload/pl-secrets" fileName="github" />

</Step>

<Step>
### <StepNumber/> Deploy GitHub OIDC Providers

First deploy the GitHub OIDC provider to all accounts where we want to grant GitHub access. The typical list of accounts
is included with the `deploy/github-oidc-provider` workflow; run the following with `SuperAdmin`:

<AtmosWorkflow workflow="deploy/github-oidc-provider" fileName="github" />

</Step>

<Step>
### <StepNumber/> Deploy the Philips Labs GitHub Runners

Now that the GitHub App has been created and the SSM parameters have been uploaded, deploy the `philips-labs-github-runners` component.

<AtmosWorkflow workflow="deploy/pl-github-runners" fileName="github" />

```console
atmos terraform output philips-labs-github-runners -s core-use1-auto 'webhook'
```
</Steps>
</Step>

<Step>
Expand All @@ -135,54 +164,10 @@ Follow the guide with the upstream module, [philips-labs/terraform-aws-github-ru
1. Provide the webhook url, should be part of the output of terraform.
1. Provide the webhook secret (`terraform output -raw <NAME_OUTPUT_VAR>`).
1. In the _"Permissions & Events"_ section and then _"Subscribe to Events"_ subsection, check _"Workflow Job"_.

1. Ensure the webhook for the GitHub app is enabled and pointing to the output of the module.
- The endpoint can be found from `atmos terraform output philips-labs-github-runners -s core-use1-auto 'webhook'`
1. Ensure the webhook for the GitHub app is enabled and pointing to the output of the module. The endpoint can be found by running `atmos terraform output philips-labs-github-runners -s core-use1-auto 'webhook'`
</Steps>
</Step>

<Step>
## <StepNumber/> Vendor Components

Vendor in the necessary components with the following workflow:

<AtmosWorkflow workflow="vendor" fileName="github" />
</Step>

<Step>
## <StepNumber/> Deploy the Philips Labs Runners

:::info

You can run all workflows at once in the right order with

<AtmosWorkflow workflow="all" fileName="github" />

:::
</Step>

<Step>
### <StepNumber/> GitHub OIDC Provider

First deploy the GitHub OIDC provider to all accounts where we want to grant GitHub access. The typical list of accounts
is included with the `deploy/github-oidc-provider` workflow; run the following with `SuperAdmin`:

<AtmosWorkflow workflow="deploy/github-oidc-provider" fileName="github" />
</Step>

<Step>
### <StepNumber/> GitHub Runners

To deploy the self-hosted runners themselves, first verify [the GitHub App requirement](#Requirements) is complete
including both SSM parameters. Next we will deploy the token rotator and then the runners themselves.

<AtmosWorkflow workflow="deploy/github-runners" fileName="github" />

If all goes well, you should now see self-hosted runners registered to your infrastructure repository in GitHub. If not,
read through the attached [FAQs](#FAQ).
</Step>


</Steps>

## Usage
Expand Down Expand Up @@ -213,9 +198,9 @@ Remove the `terraform` label from the default runner set and add the `terraform`
Since the workflows are all labeled with `terraform` already, they will automatically select the new runner set on their
next run.

# FAQ
## FAQ

## I cannot assume the role from GitHub Actions after deploying
### I cannot assume the role from GitHub Actions after deploying

The following error is very common if the GitHub workflow is missing proper permission.

Expand Down
Loading