Authentifizieren von ARC für die GitHub-API

Du kannst Actions Runner Controller (ARC) bei der GitHub-API authentifizieren, indem du eine GitHub App oder ein personal access token (classic) verwendest.

Authentifizieren von ARC mit einer GitHub App

1. Erstelle eine GitHub App, die einer Organisation gehört. Weitere Informationen finden Sie unter Registrieren einer GitHub-App. Konfiguriere die GitHub App wie folgt.

   1. Gibt unter „Homepage-URL“ Folgendes ein: https://github.com/actions/actions-runner-controller.

   2. Klicke unter „Berechtigungen“ auf die Option Repositoryberechtigungen. Verwende dann die Dropdownmenüs, um die folgenden Zugriffsberechtigungen auszuwählen. * Administration: Lese- und Schreibzugriff

      Hinweis

      Administration: Read and write ist nur erforderlich, wenn du Actions Runner Controller für die Registrierung im Bereich des Repositorys konfigurierst. Es ist nicht erforderlich, sich innerhalb des Organisationsbereiches zu registrieren.

      •   **Metadaten**: Nur Lesezugriff
        

   3. Klicke unter „Berechtigungen“ auf Organisationsberechtigungen. Verwende dann die Dropdownmenüs, um die folgenden Zugriffsberechtigungen auszuwählen.

      •           **Selbstgehostete Runner**:Lese- und Schreibzugriff
        

2. Nachdem du GitHub App erstellt hast, notiere dir den Wert für „App-ID“ auf der GitHub App-Seite. Du wirst diesen Wert später noch verwenden.

3. Klicke unter „Private Schlüssel“ auf Privaten Schlüssel generieren, und speichere die Datei .pem. Du wirst diesen Schlüssel später noch verwenden.

4. Klicke im Menü in der oberen linken Ecke der Seite auf App installieren, und klicke neben deiner Organisation auf Installieren, um die App in deiner Organisation zu installieren.

5. Nachdem du die Installationsberechtigungen für deine Organisation bestätigt hast, musst du dir die App-Installations-ID notieren. Du wirst es später verwenden. Du findest die App-Installations-ID auf der App-Installationsseite, die das folgende URL-Format aufweist:

   https://HOSTNAME/organizations/ORGANIZATION/settings/installations/INSTALLATION_ID

6. Registriere die App-ID, die Installations-ID und die heruntergeladene .pem-Datei des privaten Schlüssels aus den vorherigen Schritten in Kubernetes als Geheimnis.

   Führe den folgenden Befehl aus, um ein Kubernetes-Geheimnis mit den Werten deiner GitHub App zu erstellen.

   Hinweis

   Erstelle das Geheimnis im selben Namespace, in dem auch das gha-runner-scale-set-Diagramm installiert ist. In diesem Beispiel ist der Namespace arc-runners, um der Schnellstartdokumentation zu entsprechen. Weitere Informationen finden Sie unter Schnellstart für Actions Runner Controller.

   Bash

   kubectl create secret generic pre-defined-secret \
      --namespace=arc-runners \
      --from-literal=github_app_id=123456 \
      --from-literal=github_app_installation_id=654321 \
      --from-literal=github_app_private_key='-----BEGIN RSA PRIVATE KEY-----********'
   

   Übergebe dann mithilfe der githubConfigSecret-Eigenschaft in deiner Kopie der values.yaml-Datei den Geheimnisnamen als Verweis.

   githubConfigSecret: pre-defined-secret
   

Weitere Helm-Konfigurationsoptionen findest du unter values.yaml im ARC-Repository.

Authentifizierung von ARC mit einem personal access token (classic)

ARC kann personal access tokens (classic) verwenden, um selbstgehostete Runner zu registrieren.

1. Erstelle ein personal access token (classic) mit den erforderlichen Bereichen. Die erforderlichen Bereiche unterscheiden sich je nachdem, ob du Runner auf der Repositoryebene, Organisationsebene oder Unternehmensebene registrierst. Weitere Informationen zum Erstellen eines personal access token (classic) findest du unter Verwalten deiner persönlichen Zugriffstoken.

   Im Folgenden ist die Liste der erforderlichen personal access token-Bereiche für ARC-Runner aufgeführt.

   • Repository-Runner: repo
   • Organisations-Runner: admin:org
   • Unternehmens-Runner: manage_runners:enterprise

2. Führe den folgenden Befehl aus, um ein Kubernetes-Geheimnis mit den Werten deines personal access token (classic) zu erstellen.

   Hinweis

   Erstelle das Geheimnis im selben Namespace, in dem auch das gha-runner-scale-set-Diagramm installiert ist. In diesem Beispiel ist der Namespace arc-runners, um der Schnellstartdokumentation zu entsprechen. Weitere Informationen finden Sie unter Schnellstart für Actions Runner Controller.

   Bash

   kubectl create secret generic pre-defined-secret \
      --namespace=arc-runners \
      --from-literal=github_token='YOUR-PAT'
   

3. In deiner Kopie der values.yaml-Datei übergibst du den Secret-Namen als Referenz.

   githubConfigSecret: pre-defined-secret
   

   Weitere Helm-Konfigurationsoptionen findest du unter values.yaml im ARC-Repository.

Authentifizierung von ARC mit einem fine-grained personal access token

ARC kann fine-grained personal access tokens verwenden, um selbst gehostete Runner zu registrieren.

1. Erstelle eine fine-grained personal access token mit den erforderlichen Bereichen. Die erforderlichen Bereiche sind unterschiedlich, je nachdem, ob du Runner auf Repository- oder Organisationsebene registrierst. Weitere Informationen zum Erstellen eines fine-grained personal access token findest du unter Verwalten deiner persönlichen Zugriffstoken.

   Im Folgenden ist die Liste der erforderlichen personal access token-Bereiche für ARC-Runner aufgeführt.

   • Repository-Runner: * Administration: Lese- und Schreibzugriff

   • Organisationsläufer * Verwaltung: Lesen

     •           **Selbstgehostete Runner**:Lese- und Schreibzugriff
       

2. Führe den folgenden Befehl aus, um ein Kubernetes-Geheimnis mit den Werten deines fine-grained personal access token zu erstellen.

   Hinweis

   Erstelle das Geheimnis im selben Namespace, in dem auch das gha-runner-scale-set-Diagramm installiert ist. In diesem Beispiel ist der Namespace arc-runners, um der Schnellstartdokumentation zu entsprechen. Weitere Informationen finden Sie unter Schnellstart für Actions Runner Controller.

   Bash

   kubectl create secret generic pre-defined-secret \
      --namespace=arc-runners \
      --from-literal=github_token='YOUR-PAT'
   

3. In deiner Kopie der values.yaml-Datei übergibst du den Secret-Namen als Referenz.

   githubConfigSecret: pre-defined-secret
   

   Weitere Helm-Konfigurationsoptionen findest du unter values.yaml im ARC-Repository.

Authentifizierung der ARC mit Vault Secrets

Ab Version 0.12.0 des gha-runner-scale-set unterstützt ARC das Abrufen der GitHub-Anmeldeinformationen von einem externen Vault. Die Vault Integration wird pro Runner Scale Set festgelegt. Das bedeutet, dass du einige Scale Sets mit Kubernetes Secrets ausführen kannst, während andere Vault-basierte Secrets verwenden, je nach deinen Sicherheits- und Betriebsanforderungen.

Aktivieren der Vault-Integration

So legst du die Vault-Integration für ein Runner Scale Set fest:

1.        **Lege das `githubConfigSecret`-Feld** in deiner `values.yaml`-Datei auf den Namen des geheimen Schlüssels fest, der in deinem Tresor gespeichert ist. Dieser Wert muss eine Zeichenfolge sein.
   

2.        **Hebe die Kommentierung auf, und konfiguriere den `keyVault`-Abschnitt** in deiner `values.yaml`-Datei mit dem entsprechenden Anbieter und den entsprechenden Zugriffsdetails.
   

3.           **Stelle das erforderliche Zertifikat** (`.pfx`) für den Controller und den Listener bereit. Das kannst du tun, indem du: *das Controllerimage neu erstellt und das Zertifikat dabei gleich einschließt oder *das Zertifikat mithilfe der Felder `listenerTemplate` und `controllerManager` als Volume in den Controller und den Listener einbindest.
   

Geheimes Format

Der geheime Schlüssel, der in Azure Key Vault gespeichert ist, muss im JSON-Format vorliegen. Die Struktur hängt von der Authentifizierung ab, die du verwendest:

Beispiel: GitHub-Token

{
  "github_token": "TOKEN"
}

Beispiel: GitHub-App

{
  "github_app_id": "APP_ID_OR_CLIENT_ID",
  "github_app_installation_id": "INSTALLATION_ID",
  "github_app_private_key": "PRIVATE_KEY"
}

Konfigurieren von values.yaml für die Tresorintegration

Das Zertifikat wird als PFX-Datei gespeichert und unter /akv/cert.pfx für den Container bereitgestellt. Im Folgenden findest du ein Beispiel dafür, wie der Abschnitt „keyVault“ konfiguriert werden muss, damit dieses Zertifikat für die Authentifizierung verwendet wird:

keyVault:
  type: "azure_key_vault"
  proxy:
    https:
      url: "PROXY_URL"
      credentialSecretRef: "PROXY_CREDENTIALS_SECRET_NAME"
    http: {}
    noProxy: []
  azureKeyVault:
    clientId: <AZURE_CLIENT_ID>
    tenantId: <AZURE_TENANT_ID>
    url: <AZURE_VAULT_URL>
    certificatePath: "/akv/cert.pfx"

Bereitstellen des Zertifikats für Controller und Listener

ARC erfordert ein .pfx-Zertifikat zur Authentifizierung beim Vault. Dieses Zertifikat muss während der Controllerinstallation sowohl für die Controller- als auch für die Listenerkomponente verfügbar gemacht werden. Dies erreichst du, indem du das Zertifikat mithilfe der Felder controllerManager und listenerTemplate als Volume in deine values.yaml-Datei einbindest:

volumes:
  - name: cert-volume
    secret:
      secretName: my-cert-secret
volumeMounts:
  - mountPath: /akv
    name: cert-volume
    readOnly: true

listenerTemplate:
  volumeMounts:
    - name: cert-volume
      mountPath: /akv/certs
      readOnly: true
  volumes:
    - name: cert-volume
      secret:
        secretName: my-cert-secret

Der folgende Code ist ein Beispiel für eine Skalensatz-values.yml-Datei.

listenerTemplate:
  spec:
    containers:
      - name: listener
        volumeMounts:
          - name: cert-volume
            mountPath: /akv
            readOnly: true
    volumes:
      - name: cert-volume
        secret:
          secretName: my-cert-secret

Rechtliche Hinweise

Teile wurden von https://github.com/actions/actions-runner-controller/ unter der Apache-2.0-Lizenz übernommen:

Copyright 2019 Moto Ishizawa

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.