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

Update README.md #157

Merged
merged 1 commit into from
Jan 3, 2023
Merged

Update README.md #157

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
117 changes: 63 additions & 54 deletions openshift/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,31 +8,35 @@ There are multiple ways of installing ARC, I have chosen to use GitHub Apps to s
Prior to installing ARC, you will need to install and configure cert-manager, this can be done by installing the `cert-manager` operator from the Operator Hub. Once the operator is installed (using the defaults), we will need to setup the private CA cert & key.

1. Copy your ca.crt & ca.key files locally

2. Create a SECRET with these files in the openshift-operators namespace \
`oc create secret tls ca-key-pair --cert=ca.crt --key=ca.key`
3. I chose to provide acces to the cluster by creating a kind ClusterIssuer
```
kind: ClusterIssuer
apiVersion: cert-manager.io/v1
metadata:
name: redcloud-clusterissuer
spec:
selfSigned:
ca:
secretName: ca-key-pair
```

### ARC Installation
Releases : https://github.com/actions-runner-controller/actions-runner-controller/releases/
3. I chose to provide acces to the cluster by creating a kind ClusterIssuer
```
kind: ClusterIssuer
apiVersion: cert-manager.io/v1
metadata:
name: redcloud-clusterissuer
spec:
selfSigned:
ca:
secretName: ca-key-pair
```

### ARC Installation w/ GitHub Apps Authentication
Releases : https://github.com/actions/actions-runner-controller/releases/

1. Install the current release, we'll use the "replace --force" to install the controller on OCP or it'll complain that _"metadata.annotations: Too long: must have at most 262144 bytes"_ \
`kubectl replace --force -f https://github.com/actions/actions-runner-controller/releases/download/v0.22.0/actions-runner-controller.yaml`

1. Install the current release \
`kubectl create -f https://github.com/actions-runner-controller/actions-runner-controller/releases/download/v0.25.0/actions-runner-controller.yaml`
2. When deploying the solution for a GHES environment you need to provide an additional environment variable as part of the controller deployment \
`kubectl set env deploy controller-manager -c manager GITHUB_ENTERPRISE_URL=https://${YOUR_GHES_URL} --namespace actions-runner-system`
`kubectl set env deploy controller-manager -c manager GITHUB_ENTERPRISE_URL=https://${YOUR_GHES_SERVER} --namespace actions-runner-system`

3. Prior to 0.25 you have to set _privileged_ access \
`oc adm policy add-scc-to-user privileged -z default -n actions-runner-system`
`oc adm policy add-scc-to-user privileged -z default -n actions-runner-system`

### Deploying Using GitHub App Authentication
### GitHub App Authentication
You can create a GitHub App for either your user account or any organization, below are the app permissions required for each supported type of runner.

**Required Permissions for Repository Runners:**
Expand All @@ -49,50 +53,55 @@ You can create a GitHub App for either your user account or any organization, be
* Self-hosted runners (read / write)

### GitHub App for your organization
1. Replace the :org part of the following URL with your organization name before opening it. Then enter any unique name in the "GitHub App name" field, and hit the "Create GitHub App" button at the bottom of the page to create a GitHub App.
1. Replace the `${PARTS}` of the following URL with your GHES address & organization name before opening it. Then enter any unique name in the "GitHub App name" field, and hit the "Create GitHub App" button at the bottom of the page to create a GitHub App.

`https://github.com/organizations/:org/settings/apps/new?url=http://github.com/actions-runner-controller/actions-runner-controller&webhook_active=false&public=false&administration=write&organization_self_hosted_runners=write&actions=read&checks=read`
`https://${YOUR_GHES_SERVER}/organizations/${YOUR_ORG}/settings/apps/new?url=http://github.com/actions/actions-runner-controller&webhook_active=false&public=false&administration=write&organization_self_hosted_runners=write&actions=read&checks=read`

You will see an App ID on the page of the GitHub App you created as follows, the value of this App ID will be used later.

2. Download the private key file by pushing the "Generate a private key" button at the bottom of the GitHub App page. This file will also be used later.
3. Go to the "Install App" tab on the left side of the page and install the GitHub App that you created for your account or organization.
##### NOTE: When the installation is complete, you will be taken to a URL in one of the following formats, the last number of the URL will be used as the Installation ID later (For example, if the URL ends in settings/installations/12345, then the Installation ID is 12345).
4. Register the App ID ${APP_ID}, Installation ID ${INSTALLATION_ID}, and the downloaded private key file ${PRIVATE_KEY_FILE_PATH} to OpenShift as a secret.
```
$ kubectl create secret generic controller-manager \
-n actions-runner-system \
--from-literal=github_app_id=${APP_ID} \
--from-literal=github_app_installation_id=${INSTALLATION_ID} \
--from-file=github_app_private_key=${PRIVATE_KEY_FILE_PATH}
```

3. Go to the "Install App" tab on the left side of the page and install the GitHub App that you created for your account or organization. \
##### ```NOTE: You will need to Installation ID, to retrieve it go to your ORG that you've installed the app into, visit Settings > GitHub Apps > {YOUR_APP} > and then when you highlight the URL in your browser. The number at the end would be your Intallation ID, example: https://${YOUR_GHES_SERVER}/organizations/${YOUR_ORG}/settings/installation/${INSTALLATION_ID}.```

4. Register the App ID `${APP_ID}`, Installation ID `${INSTALLATION_ID}`, and the downloaded private key file `${PRIVATE_KEY_FILE_PATH}` to OpenShift as a secret.
```
$ kubectl create secret generic controller-manager \
-n actions-runner-system \
--from-literal=github_app_id=${APP_ID} \
--from-literal=github_app_installation_id=${INSTALLATION_ID} \
--from-file=github_app_private_key=${PRIVATE_KEY_FILE_PATH}
```

### Runner Deployments
There are additional ways to launch your runners, here I chose using kind: RunnerDeployment
#### NOTE: Keep in mind that OpenShift will not natively display your deployments, to view them as well as the later HorizontalRunnerAutoscaler, you'll need to use the full name `oc get runnerdeployment`, `oc get hra` & `oc get horizonalrunnerautoscaler`.

``` apiVersion: actions.summerwind.dev/v1alpha1
kind: RunnerDeployment
metadata:
name: example-runner-deployment
spec:
template:
#### NOTE: Keep in mind that OpenShift will not natively display your deployments, to view them as well as the later HorizontalRunnerAutoscaler, you'll need to use `oc get runnerdeployment`, `oc get hra` & `oc get horizonalrunnerautoscaler`.

```
apiVersion: actions.summerwind.dev/v1alpha1
kind: RunnerDeployment
metadata:
name: example-runner-deployment
spec:
repository: example/myrepo
---
apiVersion: actions.summerwind.dev/v1alpha1
kind: HorizontalRunnerAutoscaler
metadata:
name: example-runner-deployment-autoscaler
spec:
scaleTargetRef:
name: example-runner-deployment
minReplicas: 1
maxReplicas: 5
metrics:
- type: TotalNumberOfQueuedAndInProgressWorkflowRuns
repositoryNames:
- example/myrepo
```
template:
spec:
repository: example/myrepo
---
apiVersion: actions.summerwind.dev/v1alpha1
kind: HorizontalRunnerAutoscaler
metadata:
name: example-runner-deployment-autoscaler
spec:
scaleTargetRef:
name: example-runner-deployment
# IMPORTANT : If your HRA is targeting a RunnerSet you must specify the kind in the scaleTargetRef:, uncomment the below
#kind: RunnerSet
minReplicas: 1
maxReplicas: 5
metrics:
- type: TotalNumberOfQueuedAndInProgressWorkflowRuns
repositoryNames:
- example/myrepo

```
There are a lot of options here, so I am only showing the defaults, but if you'd like an example I have included my scripts under /manifests. Additionally, I have evaluated two custom runners - one based on docker and the other based on podman (buildah). I will include these as examples under /builds.