Levykuvan luominen

Rahtia käytettäessä saatat joutua rakentamaan omat konttikuvasi ennen niiden käyttöönottoa. Mahdollisia syitä tähän ovat muun muassa:

Sovelluksen paketointi: näin on silloin, kun sovelluksesi on saatavilla lähdekoodina tai suoritettavana tiedostona ja haluat ajaa sen Rahtissa kontteina.
Tietyt riippuvuudet: käytät valmiiksi rakennettua konttikuvaa, mutta sen sisältämien kirjastojen, työkalujen tai asetusten versiot eivät sovi tarpeisiisi.
Rootless-yhteensopivuus: monet julkiset ja avoimen lähdekoodin kuvat olettavat root-oikeudet. Rakentamalla nämä kuvat uudelleen voit varmistaa, että sovellus toimii ilman root-oikeuksia, mikä on Rahtissa pakotettu paras käytäntö.

Rahtin rekisterissä kuvan kokoraja on 5Gi. Tämä johtuu siitä, että pienemmät kuvat latautuvat nopeammin, mikä lyhentää Kubernetesin Podien käynnistysaikaa ja parantaa skaalaustoimintojen reagointikykyä. Ne käyttävät myös vähemmän tallennustilaa rekistereissä ja klusterin noodeilla, mikä on tärkeää Rahtin kaltaisissa monikäyttäjäympäristöissä. Lisäksi pienempi kuva sisältää vähemmän paketteja ja tiedostoja, mikä pienentää mahdollista hyökkäyspintaa ja vähentää vanhentuneiden tai haavoittuvien komponenttien mukaan päätymisen riskiä. Tämä helpottaa ylläpitoa ja parantaa kokonaisvaltaista tietoturvaa. Koska pienemmät kuvat sisältävät vain sen, mitä sovellus tarvitsee, ne ovat ennakoitavampia, helpompia debugata ja yksinkertaisempia toistaa eri ympäristöissä.

Kuvien rakentaminen paikallisesti

Tässä esimerkissä rakennamme mukautetun version virallisesta nginx-kuvasta, joka on rakennettu Alpine Linux -jakelun päälle, ja teemme tarvittavat muutokset, jotta siitä tulee rootless ja Rahtin ehtojen mukainen. Kuvan rakentamiseen omalla koneella tai palvelimella tarvitaan kolme vaihetta:

Luo ensin tiedosto nimeltä Dockerfile, joka sisältää ohjeet mukautetun konttikuvan rakentamiseen. Siinä määritellään käytettävä pohjakuva, lisättävät tiedostot, ajettavat komennot ja asetukset, jotka lopullisessa kuvassa tulee olla:
```
FROM nginx:alpine

# support running as arbitrary user which belongs to the root group
RUN chmod g+rwx /var/cache/nginx /var/run /var/log/nginx && \
    chown nginx.root /var/cache/nginx /var/run /var/log/nginx && \
    # users are not allowed to listen on privileged ports
    sed -i.bak 's/listen$.*$80;/listen 8081;/' /etc/nginx/conf.d/default.conf && \
    # Make /etc/nginx/html/ available to use
    mkdir -p /etc/nginx/html/ && chmod 777 /etc/nginx/html/ && \
    # comment user directive as master process is run as user in OKD anyhow
    sed -i.bak 's/^user/#user/' /etc/nginx/nginx.conf

WORKDIR /usr/share/nginx/html/
EXPOSE 8081

USER nginx:root
```
Tämä Dockerfile:
- Käyttää Docker Hub -rekisterissä ylläpidettyä nginx:alpine-kuvaa pohjakuvana.
- Antaa kirjoitusoikeudet root-ryhmälle (ei root-käyttäjälle) useisiin kansioihin, joihin nginxin täytyy voida kirjoittaa (/var/cache/nginx, /var/run, /var/log/nginx ja /etc/nginx/html/). Rahti ajaa sovelluksen satunnaisella käyttäjällä ja root-ryhmällä.
- Muuttaa portin, jota nginx kuuntelee, koska vain root saa kuunnella etuoikeutettuja portteja (<1024).
- Ja lopuksi kommentoi pois user-konfiguraatiodirektiivin.
Alkuperäisessä nginx:alpine-kuvassa on 5 kerrosta, ja Dockerfilemme RUN-direktiivi lisää uuden kerroksen.

Yksinkertaisempi esimerkki Dockerfile-tiedostosta voisi olla:
```
FROM ubuntu

RUN apt install git
```
Tämä asentaa gitin ubuntu:latest-pohjakuvaan ja lisää myös uuden kerroksen.

Katso Dockerfile -viitedokumentaatio.
Rakenna seuraavaksi konttikuva ja anna sille tagi. Tämä voidaan tehdä suorittamalla seuraava komento samassa hakemistossa kuin Dockerfile.
```
docker build . -t nginx:rootless
```
Dockerfilen ohjeet suoritetaan yksi kerrallaan lopullisen konttikuvan tuottamiseksi. Arvo, jonka annat parametrille -t, on rakennettavalle kuvalle annettava nimi ja tagi. Nimi yksilöi kuvan, ja tagi (kaksoispisteen jälkeen) yksilöi kyseisen kuvan tietyn version.

Voit nähdä rakennetun kuvan paikallisessa rekisterissäsi suorittamalla:
```
docker image ls
```
Lopuksi, jos haluat jakaa kuvasi muiden kanssa, sinun täytyy julkaista se etärekisteriin. Tätä varten sinun täytyy antaa kuvalle uusi tagi, joka osoittaa etärekisteriin, ja sitten puskea se sinne.
```
docker tag nginx:rootless <remote-registry.example.com>/<registry-username>/nginx:rootless
docker push <remote-registry.example.com>/<registry-username>/nginx:rootless
```
Huomautus

Kuvat, jotka on rakennettu muille arkkitehtuureille kuin amd64, eivät ole ajettavissa Rahtissa. Rakenna ne uudelleen amd64-koneella tai muunna ne. Voit myös rakentaa ne suoraan uudelleen Rahtissa, kuten seuraavassa osiossa kuvataan.

Rahtin käyttäminen konttikuvien rakentamiseen

Alla olevissa menetelmissä käytetään Rahtia konttikuvien rakentamiseen.

Paikallisen kansion käyttäminen rakentamiseen

Tämä menetelmä mahdollistaa kuvan rakentamisen käyttämällä paikallista kansiota, joka sisältää Dockerfilen ja muut tarvittavat projektitiedostot (lähdekoodi, suoritettavat tiedostot, asetukset jne.). Se on hyödyllinen silloin, kun Rahtin ei ole mahdollista tai kätevää kloonata git-repositoriotasi suoraan. Edellytyksenä on, että olet:

Luonut projektin Rahtiin kuten on kuvattu täällä
Kirjautunut Rahti-klusteriin oc-CLI:n avulla

Vaiheet:

Luo OKD BuildConfig, jonka build-lähde on asetettu binääriseksi. Varmista, ettet ole git-versionhallinnan alaisessa hakemistossa:

$ oc new-build --to=my-hello-image:devel --name=my-hello --binary

Tulosteen pitäisi olla suunnilleen seuraavanlainen:

    * A Docker build using binary input will be created
      * The resulting image will be pushed to image stream tag "my-hello-image:devel"
      * A binary build was created, use 'start-build --from-dir' to trigger a new build

--> Creating resources with label build=my-hello ...
    imagestream.image.openshift.io "my-hello-image" created
    buildconfig.build.openshift.io "my-hello" created
--> Success

OKD luo aktiiviseen projektiisi BuildConfig-objektin nimeltä my-hello, ja lisäksi se luo paikkamerkki- ImageStream-objektin nimeltä my-hello-image tuloksena syntyvän kuvan säilyttämistä varten.

Käynnistä build-prosessi toimittamalla build-artefaktit (eli Dockerfile ja muut riippuvuudet, jos niitä on) Rahtiin.
```
oc start-build my-hello --from-dir=/path/to/artifacts --follow
```
Kun build valmistuu onnistuneesti, tuloksena syntyvä kuva on saatavilla Rahtin kuvarekisterissä.

Source-to-Image (S2I) -mekanismin käyttäminen

Käytä S2I-buildia, kun haluat rakentaa konttikuvan suoraan lähdekoodista kirjoittamatta omaa Dockerfileä. S2I antaa Rahtin hoitaa build-prosessin käyttämällä sen oletusrakentajakuvia eri ajoympäristöille (esim. Python, Node.js, Java, Go, PHP, Ruby). Näet Rahtissa saatavilla olevien build-kuvien luettelon suorittamalla seuraavan komennon:

oc get is -n openshift

S2I on hyvä valinta, kun:

Sovelluksesi sopii hyvin standardiin ajoympäristöön (esim. Python/Flask, Node.js/Express, Java/Spring).
Haluat välttää Dockerfilejen ylläpidon.
Haluat Rahtin hoitavan riippuvuuksien asennuksen, ympäristön asetukset ja inkrementaaliset buildit.

S2I ei ole ihanteellinen, kun tarvitset täyden hallinnan konttikuvasta, mukautettuja käyttöjärjestelmäpaketteja, epästandardeja ajoympäristöjä tai monimutkaisia build-vaiheita. Tällaisissa tapauksissa Dockerfile tai binääribuild soveltuu paremmin.

Oletetaan, että sinulla on yksityinen Git-repositorio, joka sisältää Python-sovelluksen. Voit tuoda sovelluksesi buildia ja käyttöönottoa varten Rahtiin selainkäyttöliittymän tai CLI:n avulla.

Selainkäyttöliittymän käyttäminen

Napsauta selainkäyttöliittymän oikeassa yläkulmassa olevaa plus-painiketta ja valitse import from Git.

Import git project

Syötä Git-repositoriosi URL-osoite kenttään Git Repo URL. Jos repositoriosi on yksityinen, näet varoituksen "URL is valid but cannot be reached"

Import git error

Seuraavaksi sinun täytyy antaa tunnistautumistiedot. Vaihtoehtoja on kaksi: token tai yksityinen SSH-avain:
Vaihtoehto 1: tokenin käyttäminen Git-tunnistautumiseen
1. Luo Personal Access Token:
  - GitHub:
    - Siirry GitHub-tilisi asetuksiin.
    - Siirry kohtaan "Developer settings" > "Personal access tokens".
    - Napsauta "Generate new token".
    - Valitse tarvitsemasi scopet (yleensä tarvitset repo-scopen yksityisiä repositorioita varten).
    - Luo token ja kopioi se.
  - GitLab: - Siirry GitLab-profiilisi asetuksiin. - Siirry kohtaan "Access Tokens". - Anna tokenille nimi, valitse tarvittavat scopet (esim. api, read_repository) ja luo token. - Kopioi token.
2. Lisää token Rahtiin:
  - Valitse kohdassa "Source Secret" vaihtoehto "Create new Secret".
  - Anna secretin nimi ja valitse kohdassa "Authentication type" vaihtoehto "Basic Authentication".
  - Liitä token ja luo secret.
Vaihtoehto 2: yksityisen SSH-avaimen käyttäminen
1. Luo SSH-avainpari (jos sinulla ei vielä ole sellaista):
  - Avaa pääte ja suorita seuraava komento uuden SSH-avainparin luomiseksi:
```
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
```
  - Tämä luo kaksi tiedostoa: yksityisen avaimen (id_rsa) ja julkisen avaimen (id_rsa.pub).
2. Lisää julkinen avaimesi Git-hostauspalveluun:
  - GitHub:
    - Siirry GitHub-tilisi asetuksiin.
    - Siirry kohtaan "SSH and GPG keys".
    - Napsauta "New SSH key" ja liitä id_rsa.pub-tiedostosi sisältö.
  - GitLab:
    - Siirry GitLab-profiilisi asetuksiin.
    - Siirry kohtaan "SSH Keys".
    - Lisää uusi SSH-avain ja liitä sen sisältö.
3. Lisää yksityinen SSH-avain Rahtiin:
  - Valitse kohdassa "Source Secret" vaihtoehto "Create new Secret".
  - Anna secretin nimi ja valitse kohdassa "Authentication type" vaihtoehto "SSH Key".
  - Liitä yksityisen SSH-avaimesi (id_rsa) sisältö ja luo secret.

CLI:n käyttäminen

Kirjaudu Rahtiin (oc) CLI:llä:
```
oc login <cluster-url>
```

Luo uusi projekti:

oc new-project <project-name> --display-name=<display-name> --description="csc_project:<project-number>"

Luo SSH Key Secret:

oc create secret generic <secret-name> --from-file=ssh-privatekey=<path-to-private-key> --type=kubernetes.io/ssh-auth

Linkitä secret Builder Service Accountiin:
```
oc secrets link builder <secret-name>
```

Ota sovellus käyttöön:

oc new-app <repository-url> --name=<application-name>

Voit seurata buildin etenemistä:
```
oc logs bc/<application-name>
```
Kun build päättyy, tuloksena syntyvä kuva pusketaan Rahtin integroituun rekisteriin. Lisäksi konttikuva instansioidaan automaattisesti Rahtissa Deployment-objektin kautta.
Halutessasi voit julkaista sovelluksesi internetiin suorittamalla:
```
$ oc expose service <application-name>
```
Tämä luo Routen, jonka voit tarkistaa komennolla:
```
oc get route <application-name>
```
Sovellukselle voidaan käynnistää uusi build komennolla:
```
oc start-build <application-name>
```

Vaihtoehtoisesti voit käynnistää buildin GitLab- tai GitHub-repositoriosta tutustumalla webhook-dokumentaatioon.

Inline-Dockerfile-menetelmän käyttäminen

On mahdollista luoda uusi build käyttämällä komentorivillä annettua Dockerfileä. Tällöin Dockerfile itsessään upotetaan Build-objektiin, joten ulkoista Git-repositoriota ei tarvita.

oc new-build -D $'FROM almalinux:10'

Tässä esimerkissä rakennamme kuvan, joka on kopio AlmaLinux 10:stä. On myös mahdollista luoda build paikallisesta Dockerfile-tiedostosta:

cat Dockerfile | oc new-build -D -

Vianmääritys

Jos build epäonnistuu tunnistautumisongelmien vuoksi, aseta build-secret eksplisiittisesti:

oc set build-secret --source bc/<application-name> <secret-name>

Jos buildisi epäonnistuu tai on hyvin hidas Rahtissa, se voi tarkoittaa, että sinun täytyy määrittää enemmän resursseja BuildConfig-objektille. Oletuksena BuildConfig käyttää builder-Podin ajamiseen oletuspyyntöjä ja -rajoja. Tällöin sinun täytyy muokata BuildConfigin YAML-määritelmää konsolin tai CLI:n avulla.

BuildConfig-resurssien päivittäminen CLI:n avulla

Ensin sinun täytyy hakea epäonnistuneen BuildConfigin YAML-määritelmä.
```
oc get bc <name-of-failed-bc> -o yaml > fixed_buildconfig.yaml
```

Muokkaa fixed_buildconfig.yaml-tiedostoa haluamallasi editorilla lisäämällä halutut resources-määritykset .spec-kohdan alle seuraavasti:

apiVersion: build.openshift.io/v1
kind: BuildConfig
metadata:
  name: my-app-build
spec:
  source:
    type: Git
    git:
      uri: https://github.com/example/my-app.git

  strategy:
    type: Docker
    dockerStrategy: {}

  output:
    to:
      kind: ImageStreamTag
      name: my-app:latest
  resources:
    requests:
      cpu: "500m"
      memory: "1Gi"
    limits:
      cpu: "1"
      memory: "2Gi"

Info

Voit myös käyttää komentoa oc edit bc <buildconfig-name> BuildConfig-objektin muokkaamiseen.

Ota muutokset käyttöön:
```
oc apply -f fixed_buildconfig.yaml
```
Suorita build uudelleen:
```
oc start-build <buildconfig-name>
```

BuildConfig-resurssien päivittäminen selainkäyttöliittymän avulla

Siirry Rahtin konsolissa kohtaan Builds > BuildConfigs ja napsauta BuildConfigiasi.
Valitse YAML-välilehti.

Lisää halutut resources-määritykset .spec-kohdan alle seuraavasti:

apiVersion: build.openshift.io/v1
kind: BuildConfig
metadata:
  name: my-app-build
spec:
  source:
    type: Git
    git:
      uri: https://github.com/example/my-app.git

  strategy:
    type: Docker
    dockerStrategy: {}
  output:
    to:
      kind: ImageStreamTag
      name: my-app:latest

  resources:
    requests:
      cpu: "500m"
      memory: "1Gi"
    limits:
      cpu: "1"
      memory: "2Gi"

Tallenna muutokset.
Suorita build uudelleen:
```
oc start-build <buildconfig-name>
```

Huomaa, että pyyntöjen ja rajojen välinen suhde ei voi olla yli 5x. Katso lisätietoja täältä.