Observação:

• Este tutorial está disponível em um ambiente de laboratório gratuito fornecido pela Oracle.
• Ele usa valores de exemplo para credenciais, tenancy e compartimentos do Oracle Cloud Infrastructure. Ao concluir seu laboratório, substitua esses valores por valores específicos do seu ambiente de nuvem.

Usar ock-forge com o Oracle Cloud Native Environment

Introdução

A ferramenta Oracle Container Host for Kubernetes Image Builder (OCK Image Builder) cria as imagens do Oracle Container Host for Kubernetes (OCK) usadas nas implantações do Oracle Cloud Native Environment (Oracle CNE). O OCK Image Builder ajuda se a imagem OCK padrão usada pelo Oracle CNE não atender aos seus requisitos, como necessidade:

• Um layout de partição diferente da imagem OCK padrão.
• Pacotes extras ou drivers de dispositivos ausentes.

O OCK Image Builder é uma coleção de scripts de shell, sendo o principal ock-forge para gerar uma imagem de formato qcow2 inicializável para criar os nós do cluster ou uma imagem de contêiner OSTree que o Oracle CNE pode usar para atualizar nós em um contêiner em execução.

Objetivos

Neste tutorial, você aprenderá a:

• Instale, configure e use ock-forge para criar uma imagem OCK personalizada
• Criar um cluster do Oracle CNE usando a imagem do OCK personalizada
• Incluir alterações extraIgnitionInline: na imagem do OCK como padrão para todos os clusters criados ou quando usados com um cluster individual

Pré-requisitos

• Mínimo de uma instância do Oracle Linux 9

• Cada sistema deve ter o Oracle Linux instalado e configurado com:

  • Uma conta de usuário da Oracle (usada durante a instalação) com acesso sudo
  • SSH baseado em chave, também conhecido como SSH sem senha, entre os hosts
  • Um ambiente libvirt KVM de trabalho.

Implantar Ambiente Nativo do Oracle Cloud

Observação: Se estiver em execução em sua própria tenancy, leia o projeto linux-virt-labs GitHub README.md e conclua os pré-requisitos antes de implantar o ambiente de laboratório.

1. Abra um terminal no Luna Desktop.

2. Clone o projeto linux-virt-labs GitHub.

   git clone https://github.com/oracle-devrel/linux-virt-labs.git
   

3. Altere para o diretório de trabalho.

   cd linux-virt-labs/ocne2
   

4. Instale as coleções necessárias.

   ansible-galaxy collection install -r requirements.yml
   

5. Aumente o tamanho do volume de inicialização, instale o libvirt e use o Oracle Linux 9.

   cat << EOF | tee instances.yml > /dev/null
   compute_instances:
     1:
       instance_name: "ocne"
       type: "server"
       instance_ocpus: 8
       instance_memory: 128
       boot_volume_size_in_gbs: 256
   ocne_type: "libvirt"
   install_ocne_rpm: true
   update_all: true
   os_version: "9"
   EOF
   

   Observação: O OCK Image Builder funciona melhor no Oracle Linux 9.

6. Implante o ambiente de laboratório.

   Instalar usando configuração personalizada.

   ansible-playbook create_instance.yml -e localhost_python_interpreter="/usr/bin/python3.6" -e "@instances.yml"
   

   O ambiente de laboratório gratuito requer a variável extra local_python_interpreter, que define ansible_python_interpreter para execuções em execução no localhost. Essa variável é necessária porque o ambiente instala o pacote RPM do SDK para Python do Oracle Cloud Infrastructure, localizado nos módulos python3.6.

   A forma de implantação padrão usa a CPU AMD e o Oracle Linux 8. Para usar uma CPU Intel ou Oracle Linux 9, adicione -e instance_shape="VM.Standard3.Flex" ou -e os_version="9" ao comando de implantação.

   Importante: Aguarde a execução bem-sucedida do playbook e atinja a tarefa de pausa. Nesta fase do manual, a instalação do Oracle Cloud Native Environment está concluída e as instâncias estão prontas. Tome nota da reprodução anterior, que imprime os endereços IP públicos e privados dos nós que ele implanta e qualquer outra informação de implantação necessária durante a execução do laboratório.

Instalar o Oracle Container Host for Kubernetes Builder

O Oracle Container Host for Kubernetes Builder (ock-forge) é uma ferramenta de linha de comando para criar imagens de mídia inicializável baseadas no Oracle Container Host for Kubernetes (OCK) OSTree. ock-forge pode gerar imagens de máquina virtual no formato qcow2, imagens de disco bruto ou gravando diretamente em um dispositivo de bloco existente. Este tutorial demonstra como criar e usar uma imagem .qcow2 personalizada.

1. Abra um terminal e conecte-se via SSH à instância ocne.

   ssh oracle@<ip_address_of_node>
   

2. Instalar Git e Podman.

   sudo dnf install -y git container-tools
   

   O programa ock-forge requer o Podman e usa o Git para clonar os repositórios ock-forge e Oracle Container Host for Kubernetes Configuration (OCK Configuration) de GitHub.

3. Clone o repositório ock-forge.

   git clone https://github.com/oracle-cne/ock-forge
   

4. Clone o repositório de Configuração OCK.

   ock-forge usa a especificação de arquivo de árvore Configuração do OCK para o OCK para criar uma imagem.

   cd ock-forge/
   git clone https://github.com/oracle-cne/ock
   
   

Criar uma Imagem do OCK

Em seguida, você criará um dispositivo de bloco de rede, adicionará alguns pacotes Linux extras à imagem do OCK que você criará e, em seguida, usará ock-forge para executar todo o trabalho necessário para gerar uma imagem do OCK inicializável.

Ativar um Dispositivo de Bloco de Rede

O Dispositivo de Bloco de Rede (NBD) é usado por ock-forge para montar a imagem .qcow2 gerada para que o Oracle CNE possa criar um cluster do Kubernetes.

1. Carregue o módulo kernel NBD e atribua oito partições a ele.

   sudo modprobe nbd max_part=8
   

2. Confirmar se os dispositivos NBD estão presentes.

   ls -l /dev/nbd*
   

   Exemplo de Saída:

   [oracle@ocne ~]$ ls -l /dev/nbd*
   brw-rw----. 1 root disk 43,   0 Jan 15 13:55 /dev/nbd0
   brw-rw----. 1 root disk 43,  16 Jan 15 13:55 /dev/nbd1
   brw-rw----. 1 root disk 43, 160 Jan 15 13:55 /dev/nbd10
   brw-rw----. 1 root disk 43, 176 Jan 15 13:55 /dev/nbd11
   brw-rw----. 1 root disk 43, 192 Jan 15 13:55 /dev/nbd12
   brw-rw----. 1 root disk 43, 208 Jan 15 13:55 /dev/nbd13
   brw-rw----. 1 root disk 43, 224 Jan 15 13:55 /dev/nbd14
   brw-rw----. 1 root disk 43, 240 Jan 15 13:55 /dev/nbd15
   brw-rw----. 1 root disk 43,  32 Jan 15 13:55 /dev/nbd2
   brw-rw----. 1 root disk 43,  48 Jan 15 13:55 /dev/nbd3
   brw-rw----. 1 root disk 43,  64 Jan 15 13:55 /dev/nbd4
   brw-rw----. 1 root disk 43,  80 Jan 15 13:55 /dev/nbd5
   brw-rw----. 1 root disk 43,  96 Jan 15 13:55 /dev/nbd6
   brw-rw----. 1 root disk 43, 112 Jan 15 13:55 /dev/nbd7
   brw-rw----. 1 root disk 43, 128 Jan 15 13:55 /dev/nbd8
   brw-rw----. 1 root disk 43, 144 Jan 15 13:55 /dev/nbd9
   

Personalizar a Criação de Imagem do OCK

Você pode definir pacotes Linux extras para adicionar à imagem do OCK criada por ock-forge. A especificação de arquivo de árvore que OCK-forge usa está no repositório GitHub OCK Configuration.

1. Crie um diretório para o arquivo de personalização.

   mkdir /home/oracle/ock-forge/ock/configs/config-1.31/custom
   

2. Crie um arquivo de personalização para instalar os pacotes Vim e Emacs.

   cat << EOF | tee /home/oracle/ock-forge/ock/configs/config-1.31/custom/myconfig.yaml > /dev/null
   packages:
   - vim
   - emacs
   EOF
   

3. Inclua o arquivo de personalização no arquivo manifest.yaml.

   Observação: Você pode adicionar qualquer personalização adicional ao arquivo de configuração do Kubernetes para o build do Kubernetes direcionado.

   sed -i '23i - custom/myconfig.yaml' /home/oracle/ock-forge/ock/configs/config-1.31/manifest.yaml
   

4. Confirme se o novo arquivo de personalização aparece na sequência de criação de imagem do OCK definida no arquivo manifest.yaml.

   cat /home/oracle/ock-forge/ock/configs/config-1.31/manifest.yaml
   

   Exemplo de Saída:

   [oracle@ocne ock-forge]$ cat /home/oracle/ock-forge/ock/configs/config-1.31/manifest.yaml
   ref: ock
   automatic-version-prefix: "1.31"
   
   documentation: false
   boot-location: modules
   machineid-compat: false
   ...
   ...
   include:
   - base.yaml
   - ux.yaml
   - ocne.yaml
   - removals.yaml
   - config.yaml
   - custom/myconfig.yaml
   ...
   ...
   modules:
     enable:
       - container-tools:ol8
       - virt:kvm_utils3
   

Criar a Imagem do OCK

1. Use ock-forge para criar a imagem qcow2.

   sudo ./ock-forge -d /dev/nbd0 -D out/1.31/boot.qcow2 -i container-registry.oracle.com/olcne/ock-ostree:1.31 -O ./out/1.31/archive.tar -C ./ock -c configs/config-1.31 -P
   

   Onde:

   • -d: O caminho para um dispositivo de bloco existente.
   • -D: O caminho para o arquivo de imagem do disco.
   • -i: Um nome de imagem de contêiner totalmente qualificado, incluindo uma tag.
   • -C: Um diretório que contém um conjunto de configurações rpm-ostree.
   • -c: Um diretório que contém a configuração rpm-ostree a ser construída.
   • -P: Se usado, esse flag fará com que o dispositivo de bloco especificado por -d limpe sua tabela de partições e preencha-a novamente com a geometria padrão.

2. Press Enter to accept the default container registry (container-registry.oracle.com/ock-builder:latest).

   Note: The build process takes approximately 30 minutes to complete.

   Example Output:

   [oracle@ocne ock-forge]$ sudo ./ock-forge -d /dev/nbd0 -D out/1.31/boot.qcow2 -i container-registry.oracle.com/olcne/ock-ostree:1.31 -O ./out/1.31/archive.tar -C ./ock -c configs/config-1.31 -P
   + [[ -z '' ]]
   + [[ -z '' ]]
   + IGNITION_PROVIDER=qemu
   + [[ -n out/1.31/boot.qcow2 ]]
   ++ realpath -m out/1.31/boot.qcow2
   + DISK=/home/oracle/ock-forge/out/1.31/boot.qcow2
   ...
   ...
   + podman image exists ock-builder:latest
   + podman pull ock-builder:latest
   ? Please select an image: 
     ▸ container-registry.oracle.com/ock-builder:latest
       docker.io/library/ock-builder:latest
   

Modify the OCK Image

After the OCK Image build process ends, it is possible to create users, create files, configure the network, define systemd units, and much more to the qcow2 file using Butane config YAML files conforming to Butane’s schema. For more details, refer to the upstream Butane documentation.

Next, you will create a Butane-compliant YAML file to create a text file and set up a new user.

Using a Default Configuration

You can apply customizations in one of two ways:

• Use it as the default for all Oracle CNE clusters you create.
• To apply a bespoke configuration to a single Oracle CNE cluster.

The following steps demonstrate how to make your customization the default for all Oracle CNE clusters you create.

1. Make the .ocne directory.

   mkdir /home/oracle/.ocne
   

2. Add the defaults.yaml file.

   cat << EOF | tee /home/oracle/.ocne/defaults.yaml > /dev/null
   extraIgnitionInline: |
     variant: fcos
     version: 1.5.0
     storage:
       files:
         - path: /etc/myfile.txt
           contents:
             inline: Hello, world!
           mode: 0644
           user:
             id: 1000
           group:
             id: 1001
   EOF
   

   Where (see upstream documentation for more detail) :

   • variant: - Must be set to fcos for use with Oracle CNE
   • version: - Must be set to 1.5.0 for use with Oracle CNE
   • path: - /etcmyfile.txt (the path and filename for the created file)
   • mode: - Set to: 644 (you have read & write everyone else can only read it)
   • user: & group: - Assign file ownership to the UID and GID specified. This example sets it to the ocne UID and GID

3. Confirm the file created.

   cat /home/oracle/.ocne/defaults.yaml
   

Test the New OCK Image Created By ock-forge.

1. Copy the .qcow2 image to the Oracle CNE install.

   sudo cp /home/oracle/ock-forge/out/1.31/boot.qcow2 /var/lib/libvirt/images/boot.qcow2-1.31
   

2. Confirm the .qcow2 image copied.

   sudo ls /var/lib/libvirt/images
   

3. Inicie o Oracle CNE usando a imagem .qcow2.

   ocne cluster start --version 1.31 -n 1 -w 1 -u false
   

   Exemplo de Saída:

   [oracle@ocne ock-forge]$ ocne cluster start --version 1.31 -n 1 -w 1 -u false
   INFO[2025-04-14T13:47:36Z] Creating new Kubernetes cluster with version 1.31 named ocne 
   INFO[2025-04-14T13:48:34Z] Waiting for the Kubernetes cluster to be ready: ok 
   INFO[2025-04-14T13:48:35Z] Installing core-dns into kube-system: ok 
   INFO[2025-04-14T13:48:36Z] Installing kube-proxy into kube-system: ok 
   INFO[2025-04-14T13:48:39Z] Installing kubernetes-gateway-api-crds into kube-system: ok 
   INFO[2025-04-14T13:48:39Z] Installing flannel into kube-flannel: ok 
   INFO[2025-04-14T13:48:40Z] Installing ui into ocne-system: ok 
   INFO[2025-04-14T13:48:41Z] Installing ocne-catalog into ocne-system: ok 
   INFO[2025-04-14T13:48:41Z] Kubernetes cluster was created successfully  
   INFO[2025-04-14T13:48:41Z] Post install information:
   
   To access the cluster from the VM host:
       copy /home/oracle/.kube/kubeconfig.ocne.vm to that host and run kubectl there
   To access the cluster from this system:
       use /home/oracle/.kube/kubeconfig.ocne.local
   To access the UI, first do kubectl port-forward to allow the browser to access the UI.
   Run the following command, then access the UI from the browser using via https://localhost:8443
       kubectl port-forward -n ocne-system service/ui 8443:443
   Run the following command to create an authentication token to access the UI:
       kubectl create token ui -n ocne-system 
   

4. Confirme se o cluster existe.

   ocne cluster list
   

5. Defina a variável de ambiente kubeconfig para seu novo cluster.

   export KUBECONFIG=$(ocne cluster show -C ocne)
   

6. Obtenha uma lista dos nós do cluster.

   kubectl get nodes
   

7. Conecte-se ao nó de Trabalho.

   ocne cluster console --direct --node ocne-worker-1
   

8. Confirme se o arquivo myfile.txt existe.

   ls -lsa /etc/myfile.txt
   

   Exemplo de Saída:

   sh-4.4# ls -lsa /etc/myfile.txt
   4 -rw-r--r--. 1 ocne ocne 13 Apr 16 10:51 /etc/myfile.txt
   

9. Confirme o pacote emacs instalado.

   ls /bin/emacs
   

   Exemplo de Saída:

   sh-4.4# ls /bin/emacs
   /bin/emacs
   

10. Digite exit para sair do nó ocne-worker-1.

11. Conecte-se ao nó do Plano de Controle.

    ocne cluster console --direct --node ocne-control-plane-1
    

12. Confirme se o arquivo myfile.txt existe.

    ls /etc/myfile.txt
    

    Exemplo de Saída:

    sh-4.4# ls -lsa /etc/myfile.txt
    4 -rw-r--r--. 1 ocne ocne 13 Apr 16 10:50 /etc/myfile.txt
    

13. Confirme o pacote emacs instalado.

    ls /bin/emacs
    

    Exemplo de Saída:

    sh-4.4# ls /bin/emacs
    /bin/emacs
    

    Confirmando que você personalizou os nós de cluster padrão do Oracle CNE adicionando um arquivo de texto (/etc/myfile.txt) e um pacote (emacs) que não estão presentes por padrão.

14. Digite exit para sair do nó ocne-control-plane-1.

Remover o Cluster

1. Exclui o cluster.

   ocne cluster delete
   

2. Exclua o arquivo defaults.yaml.

   rm /home/oracle/.ocne/defaults.yaml
   

Atualizar a Configuração de um Único Cluster

Em seguida, você criará e aplicará um arquivo de personalização a um único cluster do Oracle CNE.

1. Crie um arquivo de configuração.

   cat << EOF | tee /home/oracle/myconfig.yaml > /dev/null
   provider: libvirt
   headless: true
   name: ocne
   kubernetesVersion: 1.31
   controlPlaneNodes: 1
   workerNodes: 1
   
   extraIgnitionInline: |
     variant: fcos
     version: 1.5.0
     storage:
       files:
         - path: /etc/myfile.txt
           contents:
             inline: Hello, world!
           mode: 0644
           user:
             id: 1000
           group:
             id: 1001
   EOF
   

2. Confirme o arquivo criado.

   cat /home/oracle/myconfig.yaml
   

3. Inicie o Oracle CNE usando a imagem .qcow2.

   ocne cluster start -u false -c /home/oracle/myconfig.yaml
   

   Exemplo de Saída:

   [oracle@ocne ~]$ ocne cluster start -u false -c /home/oracle/myconfig.yaml 
   INFO[2025-04-15T18:07:00Z] Creating new Kubernetes cluster with version 1.31 named ocne 
   INFO[2025-04-15T18:08:14Z] Waiting for the Kubernetes cluster to be ready: ok 
   INFO[2025-04-15T18:08:16Z] Installing core-dns into kube-system: ok 
   INFO[2025-04-15T18:08:16Z] Installing kube-proxy into kube-system: ok 
   INFO[2025-04-15T18:08:19Z] Installing kubernetes-gateway-api-crds into kube-system: ok 
   INFO[2025-04-15T18:08:20Z] Installing flannel into kube-flannel: ok 
   INFO[2025-04-15T18:08:20Z] Installing ocne-catalog into ocne-system: ok 
   INFO[2025-04-15T18:08:20Z] Kubernetes cluster was created successfully  
   INFO[2025-04-15T18:08:20Z] Post install information:
   
   To access the cluster from the VM host:
       copy /home/oracle/.kube/kubeconfig.ocne.vm to that host and run kubectl there
   To access the cluster from this system:
       use /home/oracle/.kube/kubeconfig.ocne.local 
   

4. Defina a variável de ambiente kubeconfig para seu novo cluster.

   export KUBECONFIG=$(ocne cluster show -C ocne)
   

5. Obtenha uma lista dos nós do cluster.

   kubectl get nodes
   

6. Conecte-se ao nó de Trabalho.

   ocne cluster console --direct --node ocne-worker-1
   

7. Confirme se o arquivo myfile.txt existe.

   ls -lsa /etc/myfile.txt
   

8. Confirme o pacote emacs instalado.

   ls /bin/emacs
   

9. Digite exit para sair do nó ocne-worker-1.

10. Conecte-se ao nó do Plano de Controle.

    ocne cluster console --direct --node ocne-control-plane-1
    

11. Confirme se o arquivo myfile.txt existe.

    ls -lsa /etc/myfile.txt
    

12. Confirme o pacote emacs instalado.

    ls /bin/emacs
    

    Confirmando que você personalizou os nós de cluster padrão do Oracle CNE adicionando um arquivo de texto (/etc/myfile.txt) e um pacote (emacs) que não estão presentes por padrão.

13. Digite exit para sair do nó ocne-control-plane-1.

Remover o Cluster

1. Exclui o cluster.

   ocne cluster delete
   

Próximas Etapas

A personalização dos arquivos de imagem do OCK do Oracle CNE permite modificar o ambiente usado nos nós do cluster do Oracle CNE Kubernetes. Continue expandindo seu conhecimento em Kubernetes e Oracle Cloud Native Environment observando nossos outros tutoriais publicados na Estação de Treinamento do Oracle Linux.

Links Relacionados

• Documentação do Oracle Cloud Native Environment
• Roteiro do Oracle Cloud Native Environment
• Oracle Linux Training Station

Mais Recursos de Aprendizagem

Explore outros laboratórios em docs.oracle.com/learn ou acesse mais conteúdo de aprendizado gratuito no canal Oracle Learning YouTube. Além disso, visite education.oracle.com/learning-explorer para se tornar um Oracle Learning Explorer.

Para obter a documentação do produto, visite o Oracle Help Center.

---

Título e Informações de Copyright

Use ock-forge with Oracle Cloud Native Environment

G33070-01

Copyright ©2025, Oracle and/or its affiliates.