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...