Manifest-filer i OKD

For at OKD skal skjønne hva det er du vil at den skal gjøre, bruker vi manifest-filer for å definere hvordan OKD skal kjøre.

Koble seg til OKD

Å koble seg til OKD gjøres via Terminal eller i nettleser. Hvilken server du kobler deg på kommer an på hvilken instans du ønsker å jobbe på.

oc login https://api.okd-dev.uio.no:6443 -u <brukernavn>-drift

I nettleser kan du besøke https://console-openshift-console.apps.okd-dev.uio.no/ for å se dev-instansen. Du må velge LDAP innlogging for å logge deg på.

Oversikt over alle clustere finner du under kom i gang med OKD.

Sette opp kobling mellom OKD og Registry

Selv om du laster opp images til Registry, vil ikke OKD automatisk vite hvilke images den skal laste ned og kjøre hos seg. Derfor må vi fortelle prosjektet (eller namespace) hvilken bruker den skal bruke for å hente imaget den skal kjøre, og når den skal gjøre det.

Sette opp ImagePull-bruker for å hente data fra Registry

For å sette opp en ImagePull-bruker kan vi laste opp en yaml-fil med de korrekte dataene:

apiVersion: v1
kind: Secret
metadata:
    name: <robot-user>-secret
    namespace: <project>
type: kubernetes.io/dockerconfigjson
data:
    .dockerconfigjson: <config>

Vi må sette et navn på hemmeligheten og et namespace, altså hvilket prosjekt som skal bruke brukeren vi nå setter opp. Det enkleste er å benytte navnet på robotbrukeren som er satt opp i Registry med suffiksen -secret.

For å generere <config> kan vi kjøre følgende kommandoer:

base64 -w 0 <<'EOF'
{
  "auths": {
    "registry.uio.no": {
      "username": "<your-org>+<robot-name>",
      "password": "<token>",
      "email": "<section>@usit.uio.no",
      "auth": "$(echo -n '<your-org>+<robot-name>:<token>' | base64)"
    }
  }
}
EOF

Etter du har kjørt kommandoen kan du erstatte <config> i yaml-filen over med strengen du får. Det er lurt å lagre dette i Vault også (og eventuelt hente det direkte fra vault ved innlasting til OKD, for ekstra sikkerhet). Husk at dette er sensitiv informasjon som gir tilgang til å lese fra Registry.

For å ta denne i bruk i OKD må du til slutt kjøre følgende kommando:

oc apply -f path/to/file.yaml

Sette opp at imaget automatisk blir hentet av OKD-deployment

Selv om du nå har en bruker for prosjektet ditt å bruke, må du fremdeles sette regler i selve deploymenten din om hvordan det hentes. Du oppretter derfor en til yaml fil som du gjerne må kalle deployment.yaml, som kan se slik ut:

apiVersion: apps/v1
kind: Deployment
metadata:
    name: <appname>
    namespace: <project>
    labels:
        app: <appname>
spec:
    replicas: 1
    selector:
        matchLabels:
            app: <appname>
    template:
        metadata:
            labels:
                app: <appname>
        spec:
            containers:
                - name: <appname>-container
                  image: <image>
                  imagePullPolicy: Always
                  ports:
                      - containerPort: 3000 # Update port to whatever your app uses

                  # --- System Resources ---
                  # Update resource amounts as needed - Do not use all resources within a OKD project (this will prevent restarts)
                  resources:
                      requests:
                          cpu: "100m" # Use proper values
                          memory: "200Mi" # Use proper values
                      limits:
                          # Do not set cpu limits
                          memory: "200Mi" # Should match memory requests
                  env:
                      - name: VAR_NAME
                        value: "some value"

                  volumeMounts:
                      - name: secrets-volume
                        mountPath: /etc/secrets
                        readOnly: true

            volumes:
                - name: secrets-volume
                  secret:
                      secretName: <appname>-secrets

            imagePullSecrets:
                - name: <secret-yaml>

Vi skal se mer på detaljene senere, men det som er relevant her er følgende snutter:

replicas: 1
selector:
    matchLabels:
        app: <appname>

Den første delen sier til OKD at vi skal kunne ha opp til 1 ekstra replika. Dette betyr at vi kan kjøre opp et image mens det gamle fremdeles kjører, som er fint når man ønsker å bytte et image på OKD uten nedetid på selve appen. Da bytter man når begge er klare slik at appen er kjørende kontinuerlig (også kjent som hotswapping).

Den andre delen sier at den vil kontrollere utrullingen til alle apper med navnet satt.

For å ta i bruk brukeren vi har satt opp må vi også spesifisere, slik som er gjort nederst:

imagePullSecrets:
    - name: <secret-yaml>

Her sier vi at <secret-yaml>, som vi satte opp over, skal brukes. Dette skal tilsvare altså <robot-user>-secret som vi satte.

Når disse to tingene er gjort, vil OKD alltid hente siste versjon lastet opp til Quay og bruke den når vi kjører en omstart av deployment-en.

Manifest-filer

Det trengs ikke å dele opp i flere filer utover en secrets fil og en deployment, fil, men det kan være fint for ordens skyld. Under er derfor plassert route og service i egne filer, men de kan legges inn i deployment.yaml dersom man ønsker det. Filnavnene kan også være hva enn du ønsker, men det er greit at de forteller hva slags type manifest de er.

For å laste opp filene kjører du bare kommandoen:

oc apply -f path/to/file.yaml

Om terminalen din er åpen i samme mappe som filen kan du istedenfor bare skrive navnet på filen.

deployment.yaml

Eksempel

apiVersion: apps/v1
kind: Deployment
metadata:
    name: <appname>
    namespace: <project>
    labels:
        app: <appname>
spec:
    replicas: 1
    selector:
        matchLabels:
            app: <appname>
    template:
        metadata:
            labels:
                app: <appname>
        spec:
            containers:
                - name: <appname>-container
                  image: <image>
                  imagePullPolicy: Always
                  ports:
                      - containerPort: 3000

                  resources:
                      requests:
                          cpu: "100m" # Use proper values
                          memory: "200Mi" # Use proper values
                      limits:
                          # Do not set cpu limits
                          memory: "200Mi" # Should match memory requests
                  env:
                      - name: VAR_NAME
                        value: "some value"

                  volumeMounts:
                      - name: secrets-volume
                        mountPath: /etc/secrets
                        readOnly: true

            volumes:
                - name: secrets-volume
                  secret:
                      secretName: <appname>-secrets

            imagePullSecrets:
                - name: <secret-yaml>

Denne filen er hovedinstruksjonen til OKD om hvordan en gitt applikasjon skal kjøres. Den definerer hvordan OKD skal starte opp containere, hente image fra Registry, sette miljøvariabler og ressurser, samt holde applikasjonen i gang over tid.

secrets.yaml

Eksempel

apiVersion: v1
kind: Secret
metadata:
    name: <appname>-secrets
    namespace: <project>
type: Opaque
data:
    var_secret: bXlQYXNzd29yZDEyMw== #myPassword123 in base64

Denne filen brukes for å lagre sensitive data som API-nøkler, tokens eller passord i OKD.

Over har vi noen metadata-felt:

For selve data-en, altså passordene, API-nøklene og tokens må verdien være base64-enkodet før det legges inn. For eksempel, hvis du har passordet myPassword123, kan du konvertere det i terminalen slik:

echo -n 'myPassword123' | base64

Resultatet kan da brukes:

var_secret: bXlQYXNzd29yZDEyMw==

På denne måten vil miljøvariabelen VAR_SECRET være tilgjengelig i containeren din med verdien myPassword123 – men selve verdien er trygt lagret i OKD og ikke synlig i klartekst.

OBS! Enten last passord/tokens inn via Vault med et script og erstatt verdiene før du laster de opp til OKD, eller oppbevar selve filen et trygt sted. Slike filer skal aldri lastes opp på GitHub eller andre steder som ikke er godkjent for røde data.

Du kan legge til flere hemmelige nøkler i samme fil ved å utvide data-blokken:

var_secret: bXlQYXNzd29yZDEyMw==
api_key: aHR0cHM6Ly93d3cueW91dHViZS5jb20vd2F0Y2g/dj1kUXc0dzlXZ1hjUQo=

Husk at alle verdier i en secret må være base64-kodet. Dette er et teknisk krav i Kubernetes-APIet, og betyr ikke at verdiene er kryptert – bare at de er kodet.

Til slutt, last opp hemmeligheten til OKD med:

oc apply -f secrets.yaml

Når dette er gjort, er hemmeligheten tilgjengelig for bruk i deployment-en din – uten at sensitive verdier kommer på avveie.

service.yaml

Eksempel

apiVersion: v1
kind: Service
metadata:
    name: <appname>-service
    namespace: <project>
spec:
    selector:
        app: <appname>
    ports:
        - protocol: TCP
          port: 3000
          targetPort: 3000

Denne filen definerer en intern Service i OKD, som fungerer som et fast kontaktpunkt for applikasjonen din. En Service kobler sammen ruten (fra route.yaml) med de faktiske Podene som kjører applikasjonen, og sørger for stabil tilgang, selv om Podene byttes ut under en omstart/redeployment.

I de fleste tilfeller bruker man samme verdi for begge, f. eks. 3000, men det er fullt mulig å oversette fra en port til en annen hvis nødvendig.

Når du har opprettet filen, laster du den opp til OKD med:

oc apply -f service.yaml

Etter det kan du bekrefte at tjenesten kjører med:

oc get svc -n <project>

Tjenesten vises da med sin interne ClusterIP og port, og fungerer som en mellommann mellom ruten og containerne dine.

Du kan lese mer om feilsøking av service-filer her.

route.yaml

Eksempel

apiVersion: route.openshift.io/v1
kind: Route
metadata:
    name: <appname>
    namespace: <project>

spec:
    host: <url>
    port:
        targetPort: 3000 # Update port to whatever your app uses
    tls:
        termination: edge # Read the OKD docs to learn which termination to use
    to:
        kind: Service
        name: <appname>-service
        weight: 100

Denne filen definerer en nettverks-rute til applikasjonen din i OKD, slik at den kan nås via nettleser eller andre tjenester. Det er OpenShift sin måte å eksponere interne tjenester til resten av UiO.

Etter at filen er opprettet, kan du bruke:

oc apply -f route.yaml

... for å dytte den til OKD. Når dette er gjort, vil OKD sette opp en DNS-rute og gjøre applikasjonen tilgjengelig på adressen du har spesifisert.

Du kan verifisere at route fungerer med kommandoen:

oc get route -n <project>

Dette viser deg blant annet URL-en til applikasjonen og om TLS er aktivert.

Les mer om...