fremforge-registry's gebruiken vanuit GitHub Actions en OpenShift

Je broncode en CI kunnen op GitHub blijven en je clusters op OpenShift, terwijl de pakketten in je fremforge-organisatie staan. Beide bereiken het register via een registry-robot: een login die bij de organisatie hoort en niet bij een persoon.

Een registry-robot:

leest, of leest en publiceert, de pakketten van één organisatie, van elk pakkettype;
kan publiceren maar niet verwijderen: het verwijderen van een pakketversie, een bestand, een containertag of een image wordt geweigerd met 403 en in het auditlog vastgelegd als registry_robot.delete_refused. Verwijderen blijft voorbehouden aan een beheerder van de organisatie, in de web-UI of met zijn eigen login;
kan geen code lezen, de web-UI niet openen en geen andere organisatie bereiken;
telt niet als gebruiker;
verloopt na hooguit 365 dagen, waarna hij en elk token dat hij heeft niet meer werken;
staat, met wie hem heeft aangemaakt, vermeld onder Organisatiebeheer → Beveiliging → Toegang → Registry-robots, en elke aanmaak, rotatie, verwijdering en geweigerde verwijdering van een pakket staat in het auditlog van de organisatie.

In de eigen CI van fremforge heb je er geen nodig: een Forgejo Actions-job heeft al een token voor de pakketten van zijn eigen organisatie. Zie Publiceren vanuit Forgejo Actions.

Een robot aanmaken

In de console: Organisatiebeheer → Beveiliging → Toegang → Registry-robots → Robot aanmaken. Kies Pakketten lezen voor een pull secret en Pakketten lezen en publiceren (niet verwijderen) voor een CI-job die publiceert.

De pagina toont daarna één keer de gebruikersnaam en het token van de robot. Kopieer beide; het token wordt niet opnieuw getoond. Ben je het kwijt, dan geeft Token roteren een nieuw token uit en trekt het oude meteen in.

Of met de API, met een API-token met de scope policy:write:

curl -sS -X POST "https://frem.sh/_app/api/v1/orgs/<org>/registry-robots" \
  -H "Authorization: Bearer $FREMFORGE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "github-publish", "access": "write", "expires_in_days": 90}'

Het antwoord bevat username en token. access is read of write, en expires_in_days is 1 tot 365 (standaard 90). Roteer met POST /orgs/<org>/registry-robots/<id>/rotate, optioneel met {"expires_in_days": n} om een nieuwe vervaldatum in te stellen, en verwijder met DELETE /orgs/<org>/registry-robots/<id>.

De gebruikersnaam heeft de vorm <org prefix>-fremforge-bot-reg-<8 hex characters>. Het voorvoegsel is de naam van je organisatie, zo nodig ingekort zodat de gebruikersnaam in 40 tekens past: een robot van acme-infrastructure-team heet bijvoorbeeld acme-infrastr-fremforge-bot-reg-1a2b3c4d. Kopieer de gebruikersnaam die de pagina of de API toont, in plaats van hem zelf uit de naam van de organisatie samen te stellen. Elke client hieronder gebruikt hem als gebruikersnaam en het token als wachtwoord.

GitHub Actions

Sla de robot op in de GitHub-repository of -organisatie: de gebruikersnaam als de variabele FREMFORGE_REGISTRY_USER en het token als het secret FREMFORGE_REGISTRY_TOKEN. Zet ORG op je fremforge-organisatie.

Containerimages

- name: Push to fremforge
  env:
    FREMFORGE_USER: ${{ vars.FREMFORGE_REGISTRY_USER }}
    FREMFORGE_TOKEN: ${{ secrets.FREMFORGE_REGISTRY_TOKEN }}
    ORG: <org>
  run: |
    echo "$FREMFORGE_TOKEN" | docker login frem.sh -u "$FREMFORGE_USER" --password-stdin
    docker build -t "frem.sh/$ORG/app:$GITHUB_SHA" .
    docker push "frem.sh/$ORG/app:$GITHUB_SHA"

Pullen gaat op dezelfde manier, met docker pull frem.sh/<org>/app:<tag>. Een gepushte tag kan niet worden overschreven als onveranderlijke releases voor de organisatie aanstaan.

npm

npm stuurt een token alleen naar een register-URL die exact overeenkomt, dus geef het het register van de scope en het token voor die URL:

- name: Publish to fremforge
  env:
    FREMFORGE_TOKEN: ${{ secrets.FREMFORGE_REGISTRY_TOKEN }}
    ORG: <org>
  run: |
    printf '@<scope>:registry=https://frem.sh/api/packages/%s/npm/\n//frem.sh/api/packages/%s/npm/:_authToken=%s\n' \
      "$ORG" "$ORG" "$FREMFORGE_TOKEN" > .npmrc
    npm publish

Met dezelfde .npmrc installeer je @<scope>/…-pakketten met npm install.

PyPI

- name: Publish to fremforge
  env:
    FREMFORGE_USER: ${{ vars.FREMFORGE_REGISTRY_USER }}
    FREMFORGE_TOKEN: ${{ secrets.FREMFORGE_REGISTRY_TOKEN }}
    ORG: <org>
  run: |
    python -m pip install twine
    twine upload --repository-url "https://frem.sh/api/packages/$ORG/pypi" \
      -u "$FREMFORGE_USER" -p "$FREMFORGE_TOKEN" dist/*

Installeer met de inloggegevens van de robot in de index-URL:

pip install --index-url "https://$FREMFORGE_USER:$FREMFORGE_TOKEN@frem.sh/api/packages/$ORG/pypi/simple/" <package>

Maven

Voeg een server toe met de id die je pom.xml gebruikt voor de fremforge-repository, en lees de robot uit de omgeving:

<settings>
  <servers>
    <server>
      <id>fremforge</id>
      <username>${env.FREMFORGE_USER}</username>
      <password>${env.FREMFORGE_TOKEN}</password>
    </server>
  </servers>
</settings>

- name: Publish to fremforge
  env:
    FREMFORGE_USER: ${{ vars.FREMFORGE_REGISTRY_USER }}
    FREMFORGE_TOKEN: ${{ secrets.FREMFORGE_REGISTRY_TOKEN }}
  run: mvn --batch-mode -s .ci/settings.xml deploy

met de repository in pom.xml zoals bij Maven: https://frem.sh/api/packages/<org>/maven.

Zonder opgeslagen secret: het OIDC-token van GitHub

Een robot kan ook het eigen OIDC-token van GitHub Actions accepteren in plaats van een opgeslagen registertoken. Geef de robot het numerieke id van je GitHub-organisatie (of -gebruiker), en optioneel één repository, onder GitHub Actions bij de robot, of met github_repository_owner_id en github_repository in de API. Een job van die eigenaar vraagt dan zijn OIDC-token aan met de audience https://frem.sh/<org> (permissions: id-token: write) en wisselt het in bij POST https://frem.sh/_app/api/v1/registry/oidc-token (org, robot, id_token) voor de gebruikersnaam van de robot en een token dat 1 uur geldig is. De uitwisseling staat in de API-referentie onder Registry-robots; elk token dat ze uitgeeft, staat in het auditlog met de repository, de ref en het run-id.

SBOM’s

SBOM’s gaan naar de API van fremforge, niet naar het register, met een API-token met de scope sboms:write. Zie SBOM’s uploaden vanuit GitHub Actions.

OpenShift en Kubernetes

Haal images uit fremforge op met een robot met alleen leestoegang als image pull secret:

kubectl create secret docker-registry frem-sh \
  --docker-server=frem.sh \
  --docker-username=<robot username> \
  --docker-password=<robot token> \
  --namespace=<namespace>

en verwijs ernaar vanuit de workload:

spec:
  imagePullSecrets:
    - name: frem-sh
  containers:
    - name: app
      image: frem.sh/<org>/app:1.4.2

OpenShift leest hetzelfde secret van het type kubernetes.io/dockerconfigjson. Roteer de robot voordat hij verloopt en vervang het secret door een secret dat met het nieuwe token is gemaakt.

Hosts die je in een egress-firewall moet toestaan

Host	Poort	Gebruikt voor
`frem.sh`	443	Elk verzoek aan het register: logins, indexen, uploads, en manifests en lagen van containerimages
`obs.eu-de.otc.t-systems.com`	443	Downloads van andere pakketbestanden dan containerimages: npm-tarballs, wheels, JAR’s enzovoort

Een download van een ander pakketbestand dan een containerimage antwoordt met 303 en een kortlevende ondertekende link naar het bestand in de objectopslag op obs.eu-de.otc.t-systems.com, die de client volgt. Die naam is een CNAME van obs.lz01.eu-de.otc.t-systems.com, dus een firewall die elke naam in de keten controleert, heeft beide nodig. Lagen van containerimages worden door frem.sh zelf geleverd.

frem.sh wordt via een CDN geleverd, dus de adressen veranderen: sta het toe op naam, niet op IP-adres.

Dependency-proxy

Een robot met leestoegang haalt met hetzelfde token ook pakketten op via de dependency-proxy van je organisatie (Docker Hub, npm, PyPI en de andere openbare registers). Zie Authenticatie.

Dependency-proxy