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.

Authentifizierung von ARC mit einer GitHub App

1. Erstelle eine GitHub App, die einer Organisation gehört. Weitere Informationen findest du 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 der Actions Runner Controller konfiguriert wird, um auf Repository-Ebene registriert zu werden. 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 Erste Schritte mit 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-Läufer: 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 Erste Schritte mit Actions Runner Controller.

   Bash

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

3. Übergeben Sie in Ihrer Kopie der values.yaml-Datei den Geheimnamen als Verweis.

   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 selbstgehostete Runner zu registrieren.

1. Erstelle ein fine-grained personal access token mit den erforderlichen Bereichen. Die erforderlichen Bereiche unterscheiden sich je nachdem, ob Sie Runner auf Repository- oder Organisationsebene registrieren. 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 Erste Schritte mit Actions Runner Controller.

   Bash

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

3. Übergeben Sie in Ihrer Kopie der values.yaml-Datei den Geheimnamen als Verweis.

   githubConfigSecret: pre-defined-secret
   

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

ARC-Authentifizierung mit Tresorgeheimnissen

Ab Version 0.12.0 des gha-runner-scale-set unterstützt ARC das Abrufen der GitHub-Anmeldeinformationen von einem externen Vault. Die Tresorintegration wird pro Runner-Scale-Set konfiguriert. Dies bedeutet, dass Sie bestimmte Skalierungsgruppen mithilfe von Kubernetes-Geheimnissen ausführen können, während andere tresorbasierte Geheimnisse verwenden, je nach Ihren sicherheitsbezogenen und operativen Anforderungen.

Aktivierung der Tresorintegration

So richtest du die Tresor-Integration für einen Runner-Skalierungssatz ein:

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.