Provisionamento e configuração

Esse guia introduz a configuração e especificação cuidadosa para configuração FOS humanamente amigável em arquivos YAML.

Ao invés de ler essas instruções detalhadas, usuários avançados irão preferir referenciar a configuration specification para uma lista abreviada de opções.

Pequena descrição do Ignition

Ignition é uma utilidade de provisionamento que lê um arquivo de configuração (no formato JSON) é provê um sistema FCOS baseado nessa configuração. Componentes configuráveis incluem armazenamento e sistema de arquivos, unidades do systemD e usuários.

Ignition é executado apenas durante a primeira inicialização do sistema (no initramfs). Porque o ignition é executado tão cedo no processo de inicialização, ele pode reparticionar discos, formatar sistemas de arquivos, criar usuários, e escrever arquivos antes que o userspace comece a inicializar. Como um resultado, serviços do systemd já são escritos no disco quando o systems inicia, acelerando o tempo para inicializar.

Processo de configuração

Configurações ignition são formatadas como JSON, que é rápido e fácil para a leitura de uma máquina. Contudo, esses arquivos não são fáceis para um humano ler ou escrever, a solução é um processo de configuração em dois passos que é amigável tanto para as máquinas, quanto para os humanos:

  1. Produzir um arquivo de configuração do Fedora CoreOS (FCC) formatado em YAML.

  2. Executar o transpilador de configuração do Fedora CoreOS (fcct) para converter o arquivo YAML em um arquivo JSON de Ignition.

Durante o processo de transpilação, fcct verifica a syntaxe do arquivo YAML, que pode detectar erros antes que você use-o para lançar o sistema FCOS.

Uma vez que você tenha um arquivo de configuração ignition (.ign), você pode usa-lo para inicializar um sistema FCOS em uma VM ou instala-lo na máquina física.

Estrutura de Arquivos FCC

O arquivo FCC segue a syntaxe YAML e contém os seguintes nós de alto nível:

  • variant: especifica fcos como o sistema operacional

  • version: especifica a versão de fcct

  • ignition: especifica uma configuração remota (para conveniência ou para plataformas que não permitem a "Ingestão" de grandes arquivos de configuração)

  • storage: provisiona armazenamento e configura o sistema de arquivos

  • systemd: controla unidades do systemd

  • passwd: configura usuários

arquivos YAML devem ter identificação consistente. Veja YAML Specification para mais detalhes.

metadados de arquivo FCC (variant and version)

As primeiras 2 linhas de um arquivo FCC define fcos como o sistema operacional e a versão semântica da especificação do documento (ex: 1.1.0). Ambas as linhas são necessárias.

Exemplo de metadados de um arquivo FCC
variant: fcos
version: 1.1.0

Ignition metadata (ignition)

The optional ignition block defines the metadata for the Ignition configuration. It allows you to specify a remote configuration file for platforms that do not allow the direct ingestion of large configuration files. It tells Ignition to start the first boot of FCOS, at which time, Ignition will fetch the specified Ignition file from a remote server.

Nós

The ignition node contains the following nodes:

  • config - provides the location of the remote Ignition file and specifies whether to merge it with the current file or replace it.

  • timeouts - specifies how to handle http responses.

  • security - specifies a tls certificate authority, if necessary.

Remote configuration file (config)

The first line of the config node specifies whether you want to merge or replace the remote configuration. Regardless of this choice, the following lines are the same:

  • source defines the remote location as a URL. The supported schemes are http, https, s3, tftp, and data.

  • verification is optional but recommended when using the http scheme. It contains a hash of the configuration

    • hash provides the hash string in the form <type>-<value> where type is sha512.

Handling HTTP responses (timeouts)

This node is optional but recommended when fetching Ignition files via http or https.

  • http_response_headers is an integer for the time to wait (in seconds) for the server’s response headers (but not the body) after making the request. The default is 10. To specify no timeout, set the value to 0.

  • http_total is an integer for the time limit (in seconds) for the entire operation (connection, request, and response), including any retries. The default is 0 for no timeout.

Network security (security)

This optional node provides options related to TLS when fetching an Ignition file via https. It contains the tls object, which contains the certificate_authorities, a list of certificate authorities (in addition to system authorities) to be used for TLS verification. All certificate authorities must have a unique source:

  • source is a string that specifies the URL of the certificate in PEM format. The supported schemes are http, https, s3, tftp, and data.

  • verification is optional but recommended when using the http scheme. It contains a hash of the certificate.

    • hash provides the hash string in the form <type>-<value> where type is sha512.

Note that certificate authorities listed here are not automatically added to the host filesystem. They are solely used by Ignition itself when fetching over https. If you’d like to also install them on the host filesystem, include them as usual under the storage.files array.

Exemplos

The following examples show how to retrieve an Ignition file from a remote source. They are both set to replace the current configuration with a remote Ignition file.

Retrieving a remote Ignition file via http
variant: fcos
version: 1.1.0
ignition:
  config:
    replace:
      source: http://example.com/sample.ign
      verification:
        hash: sha512-e2bb19fdbc3604f511b13d66f4c675f011a63dd967b97e2fe4f5d50bf6cb224e902182221ba0f9dd87c0bb4abcbd2ab428eb7965aa7f177eb5630e7a1793e2e6
Retrieving a remote Ignition file via https
variant: fcos
version: 1.1.0
ignition:
  config:
    replace:
      source: https://example.com/sample.ign
  security:
    tls:
      certificate_authorities:
        - source: https://example.com/source1
          verification:
            hash: sha512-e2bb19fdbc3604f511b13d66f4c675f011a63dd967b97e2fe4f5d50bf6cb224e902182221ba0f9dd87c0bb4abcbd2ab428eb7965aa7f177eb5630e7a1793e2e6

Especificação de armazenamento

Esta seção descreve o formato YAML da configuração FCOS (FCC) para definir o estado desejado de armazenamento associado a uma instância FCOS.

O bloco storage contém uma lista de objetos, que pode ser do seguinte tipo:

  • disks: Lista de discos

  • raid: Lista dos arrays RAID

  • filesystems: Lista de sistemas de arquivos

  • files: Lista de arquivos a serem gravados

  • directories: Lista de diretórios a serem criados

  • links: lista de Links a serem criados

Discos

Cada entrada no nó disks deve corresponder a um dispositivo único. Para cada dispositivo, especifique uma lista de partições GPT. A menos que especificado como opcional, todos os nós são obrigatórios. O conteúdo dos disks é o seguinte:

  • device (string): Caminho absoluto do dispositivo de disco. Os discos são normalmente referenciados pelos links simbólicos /dev/disk/by-*. Evite especificar o dispositivo de disco /dev/sdx diretamente: quando novos discos são inseridos, o sistema pode reenumerar os dispositivos na inicialização. Isso pode mudar a ordem dos dispositivos /dev/sdx. Os links simbólicos /dev/disk/by-* sempre apontam para os dispositivos corretos.

  • wipe_table (booleano, opcional): Quando` true`, o Ignition apaga a tabela de partição antes de continuar. Caso contrário, as entradas de partição existentes na tabela serão deixadas sozinhas.

  • partitions (lista de objetos, opcional): Lista de partições a serem gravadas na tabela de partição do dispositivo. Cada partição ocupa um slot na tabela. Você pode especificar o slot diretamente com o nó number ou especificar` number: 0` e fornecer um label exclusivo.

    • label (string, opcional): GPT PARTLABEL para a partição.

    • número (inteiro, opcional): número do slot ocupado pela partição, começando em 1. Para usar o próximo slot disponível, especifique` 0`. Nesse caso, você também deve especificar um label exclusivo.

    • size_mib (inteiro, opcional): Tamanho da partição em mebibytes. Se 0, o tamanho da partição é o maior possível. Nota: 1 mebibytes = 1024 * 1024 bytes.

    • start_mib (inteiro, opcional): Posição inicial da partição a partir do início do disco, em mebibytes. Se for 0, a partição será colocada no início do maior bloco disponível.

    • type_guid (string, opcional): GUID do tipo de partição. Se omitido, o padrão é 0FC63DAF-8483-4772-8E79-3D69D8477DE4, o GUID do sistema de arquivos nativo do Linux. A lista de referência final para o tipo de GUIDs é atualmente o arquivo parttypes.cc no código-fonte do GPT fdisk. Uma lista mais legível pode ser encontrada no GUID Partition Table article on Wikipedia.

    • guid (string, opcional, deve ser único): GUID da partição. Você pode omitir isso ao criar novas partições.

    • wipe_partition_entry (boolean, optional)

      • verdadeiro: o Ignition apaga qualquer partição existente que não corresponda a esta entrada.

      • falso: a ignição deixa a partição inalterada, que falhará.

    • should_exist (booleano, opcional). O padrão é true.

      • verdadeiro: se true e ainda não existir, a partição com o`number` especificado é criada. Se a partição existe e wipe_partition_entry é` false`, então number deve ser especificado como um inteiro diferente de zero, e` label`, start_mib,` size_mib`, guid e` type_guid` devem todos ser omitido.

      • false: If false and the partition exists, Ignition looks at the wipe_partition_entry value and deletes the partition if true, or fails if false.

Example for defining a disk containing some partitions
variant: fcos
version: 1.1.0
storage:
  disks:
    -
      # Mandatory. We use the World-Wide Number ID of the drive to ensure
      # uniqueness.
      device: /dev/disk/by-id/wwn-0x50014e2eb507fcdf
      # This ensures that the partition table is re-created, along with all
      # the partitions.
      wipe_table: true
      partitions:
        # The first partition (slot number 1) is 32 GiB and starts at the
        # beginning of the device. Its type_guid identifies it as a Linux
        # swap partition.
        - label: part1
          number: 1
          size_mib: 32768
          start_mib: 0
          type_guid: 0657fd6d-a4ab-43c4-84e5-0933c84b4f4f
        # The second partition (implicit slot number 2) will be placed after
        # partition 1 and will occupy the rest of the available space.
        # Since type_guid is not specified, it will be a Linux native
        # partition.
        - label: part2
          number: 0

Raid

Every entry under the raid node must correspond to a unique RAID array. The resulting configuration is implemented as an mdadm "software" RAID. The contents of raid is as follows. Unless specified as optional, all nodes are mandatory.

  • name (string): Name of the resulting md device.

  • level (string): Redundancy level of the array. See the supported levels in the Fedora mdadm man page. Examples: linear, raid0, raid.

  • devices (list of strings): List of devices that should be part of the array, referenced by absolute path.

  • spares (optional, integer): Number of spares in the array, if applicable.

  • options (optional, list of strings): Additional options to be passed to mdadm.

File systems

Entries under the filesystems node list the file systems to be created and mounted. Each file system must have a unique device. The contents of filesystems is as follows. Unless specified as optional, all nodes are mandatory.

  • path (string): Mount point of of the filesystem while Ignition is running, relative to where the root filesystem will be mounted. This is not necessarily the same as where it should be mounted in the real root, but you should set it as such.

  • device (string): Absolute path of the device.

  • format (string): File system "format" (ie - file system type). Accepted values: ext4, btrfs, xfs, vfat, or swap.

  • wipe_filesystem (boolean, optional): If true, the device is wiped before the file system is created.

  • label (string, optional): Label of the file system.

  • uuid (string, optional): UUID of the file system.

  • options (list of strings, optional): Additional options to be passed to mkfs.

Example for defining a file system on a RAID storage device
variant: fcos
version: 1.1.0
storage:
  disks:
  # This defines two partitions, each on its own disk. The disks are
  # identified by their WWN.
  - device: /dev/disk/by-id/wwn-0x50014ee261e524e4
    wipe_table: true
    partitions:
    -
      # Each partition gets a human-readable label.
      label: "raid.1.1"
      # Each partition is placed at the beginning of the disk and is 64 GiB
      # long.
      number: 1
      size_mib: 65536
      start_mib: 0
  - device: /dev/disk/by-id/wwn-0x50014ee0b8442cd3
    wipe_table: true
    partitions:
    - label: "raid.1.2"
      number: 1
      size_mib: 65536
      start_mib: 0
  # We use the previously defined partitions as devices in a RAID1 md array.
  raid:
    - name: publicdata
      level: raid1
      devices:
      - /dev/disk/by-partlabel/raid.1.1
      - /dev/disk/by-partlabel/raid.1.2
  # The resulting md array is used to create an EXT4 file system.
  filesystems:
    - path: /var/publicdata
      device: /dev/md/publicdata
      format: ext4
      label: PUB
Example for adding a /var partition to the primary disk
variant: fcos
version: 1.1.0
storage:
  disks:
  -
    # The name of the primary block device. In virtio-based setups, this is
    # likely `/dev/vda`. Elsewhere, it's likely `/dev/sda`.
    device: /dev/vda
    # We do not want to wipe the partition table since this is the primary
    # device.
    wipe_table: false
    partitions:
    - size_mib: 0
      start_mib: 0
      # We assign a descriptive label to the partition. This is important
      # for referring to it in a device-agnostic way in other parts of the
      # configuration.
      label: var
  filesystems:
    - path: /var
      device: /dev/disk/by-partlabel/var
      format: xfs
systemd:
  units:
    -
      # We need to create a systemd mount unit so that /var actually gets
      # mounted on /var.
      name: var.mount
      enabled: true
      contents: |
        [Unit]
        Before=local-fs.target
        [Mount]
        Where=/var
        What=/dev/disk/by-partlabel/var
        [Install]
        WantedBy=local-fs.target

Files

The files node lets you define a list of files, identified by a unique path, that Ignition will create with the required contents and attributes as needed.

An empty file would not be very useful, so the files can be defined with a contents option to specify either a source from which the file will be copied, or inline data.

The contents of files is as follows. Unless specified as optional, all nodes are mandatory.

  • path (string, must be unique): Absolute path of the file to be created.

  • overwrite (boolean, optional): Defaults to false. If true, source must be specified, and any preexisting file of the specified path will be overwritten with the contents of source.

  • contents (object, optional): Specifies the contents of the file.

    • compression (string, optional): Type of compression of the source. Possible values are null or gzip. Defaults to null. Compression cannot be specified if source uses an s3 scheme.

    • source (string, optional): Mandatory if overwrite is true. Mutually exclusive with option inline. Specifies the URL of the source to be copied to the path. Supported schemes are http, https, tftp, s3, and data. If you use the http scheme, you should specify a verification option to ensure the remote contents have not changed. If source is omitted, Ignition checks if the file already exists:

      • File exists: Ignition does nothing.

      • File does not exist: Ignition creates an empty file.

    • inline (string, optional): Mutually exclusive with option source. Specifies a string to be written to the file.

    • verification (object, optional): Tells Ignition to verify the contents of the file. Currently, only one verification option has been implemented: hash.

      • hash (string, mandatory if verification is specified): Hash of the file contents, in the form <type>-<value>. The only supported type is sha512.

  • append (object list, optional): This node has the same options as source. It specifies contents to be appended to the (presumably existing) file.

    • compression: See contents.

    • source: See contents.

    • inline: See contents.

    • verification: See contents.

      • hash: See contents.

  • mode (integer, optional): Specifies the file’s permission or mode. If mode is not specified, Ignition checks to see if the file already exists:

    • File exists: Keep the existing file mode if overwrite is false and source is not specified. Otherwise, set mode to octal 0644.

    • File does not exist: mode defaults to octal 0644.

  • user (object, optional): Specifies the user ID of the file owner. Either an ID or name must be specified.

    • id (integer, optional): User ID of the owner.

    • name (string, optional): User name of the owner.

  • group (object, optional): Specifies the group of the file owner. Either an ID or name must be specified.

    • id (integer, optional): Group ID of the owner.

    • name (string, optional): Group name of the owner.

Directories

The directories node specifies a list of directories, identified by a unique path, that Ignition creates as needed.

The directories structure is similar to the files structure. Unless specified as optional, all nodes are mandatory.

  • path (string): See Files.

  • overwrite (boolean, optional): Defaults to false. If true, preexisting files or directories at the specified path are removed. If overwrite is false and a file system object already exists at the specified path, Ignition checks the type of the existing file system object:

    • Existing path is a directory: Ignition does nothing

    • Existing path is not a directory: Ignition fails.

  • mode (integer, optional): Specifies the directory’s permission or mode. If mode is not specified, Ignition checks to see if the directory already exists:

    • Directory exists: if overwrite is false, Ignition does nothing, otherwise the mode is set to octal 0755.

    • Directory does not exist: The mode is set to 0755.

  • user: Specifies the directory owner. See Files.

    • id: See Files

    • name: See Files

  • group: Specifies the directory group. See Files.

    • id: See Files

    • name: See Files

The links node lets you specify links (hard or symbolic) to be created by Ignition as needed.

The contents of links is as follows. Unless specified as optional, all nodes are mandatory.

  • path (string, must be unique): Absolute path of the link to be created.

  • overwrite (boolean, optional): Defaults to false. If false and a link already exists at the specified path, Ignition sets only the owner and group.

  • user: Specifies the link owner. See Files.

    • id: See Files.

    • name: See Files.

  • group: Specifies the link group. See Files.

    • id: See Files.

    • name: See Files.

  • target (string): Target path of the link.

  • hard (boolean, optional): Defaults to false. If true, Ignition creates a hard link. If false, it creates a symbolic link

Example for defining files, directories and links
variant: fcos
version: 1.1.0
storage:
  # This creates a directory. Its mode is set to 0755 by default, that
  # is, readable and executable by all, and writable by the owner.
  directories:
  - path: /opt/tools
    overwrite: true
  files:
    -
      # Creates a file /var/helloworld containing a string defined in-line.
      path: /var/helloworld
      overwrite: true
      contents:
        inline: Hello, world!
      # Sets the file mode to 0644 (readable by all, also writable by the
      # owner).
      mode: 0644
      user:
        # The owner uid and group are defined by their numerical IDs.
        id: 500
      group:
        id: 500
    -
      # We need the nifty (and alas imaginary) transmogrifier tool.
      path: /opt/tools/transmogrifier
      overwrite: true
      # Deploys this tool by copying an executable from an https link. The
      # file is compressed with gzip.
      contents:
        source: https://mytools.example.com/path/to/archive.gzip
        compression: gzip
        verification:
          # The hash is sha512- followed by the 128 hex characters given by
          # the sha512sum command.
          hash: sha512-5c84785eb10c9efdea1f...
      # Makes the tool file readable and executable by all.
      mode: 0555
  links:
    -
      # Creates a symlink to the tool location from /usr/local/bin. This is
      # useful to let local processes invoke this tool without altering
      # their PATH environment variable.
      path: /usr/local/bin/transmogrifier
      overwrite: true
      target: /opt/tools/transmogrifier
      hard: false

Configurando unidades do systemd (systemd)

O nó systemd de um arquivo FCC permite que você adicione e configure unidades systemd na máquina FCOS.

Nós

O nó systemd contém um nó de nível superior: uma lista de unidades. Para cada unidade, as seguintes opções estão disponíveis:

  • name (string, required, must be unique): the full name of the unit in the form of thing.service.

  • enabled (boolean): When set to true, the unit is enabled. By default, the service is unmodified. For a unit to run, it must have an [Install] section.

  • mask (boolean): determines whether the unit is masked. When set to true, the service is masked by a symlink to /dev/null.

  • contents (string): the contents of the unit.

  • dropins (list of objects): a list of drop-ins for the unit.

    • name (string, required, must be unique): the name of the drop-in, which must have a suffix of .conf.

    • contents (string): the contents of the drop-in.

Exemplos

Running Containers shows some examples of adding systemd units to an FCC file.

Configuring Users (passwd)

The passwd node allows you to create, modify, and configure FCOS users.

FCOS has a default privileged user named core. You can use this user for system administration tasks. Use the passwd node to modify this user’s attributes, as shown below.

Nós

The top-level nodes for passwd include users and groups. These are both lists of objects.

  • users (list of objects): the lists of accounts to create on FCOS.

    • name (string, required, must be unique): the username

    • password_hash (string): the hashed password for the account.

    • ssh_authorized_keys (list of strings, each must be unique): a list of SSH keys to be added as an SSH key fragment in the user’s home directory (.ssh/authorized_keys.d/ignition).

    • uid (integer): the user ID of the account

    • gecos (string): the GECOS field of the account

    • home_dir (string): the home directory of the account

    • no_create_home (boolean): when set to true, no home directory is created for the user. This does not have any effect on any existing home directory.

    • primary_group (string): the name of the primary group of the account

    • groups (list of strings): the list of supplementary groups of the account

    • no_user_group (boolean): when true, does not create a user group for the account. This has no effect on any existing groups.

    • no_log_init (boolean): when set to true, does not add the user to the lastlog and faillog databases. This has no effect on any existing accounts.

    • shell (string): the login shell of the new account

    • system (boolean): when set to true, creates the account as a system account. Has no effect on an existing account.

  • groups (list of objects): a list of groups to be added

    • name (string, required, must be unique): the name of the group

    • gid (integer): the group ID of the group

    • password_hash (string): the hashed password for the group

    • system (boolean): when set to true, the group is created as a system group. Has no effect on existing groups.

Exemplos

Producing an Ignition File is a tutorial for how to provide an SSH key for login of the existing core user.

You can also add a password hash to this user, specify the user’s groups, and add more users as shown below:

Example for modifying and adding users:
  passwd:
  users:
    - name: core
      ssh_authorized_keys:
        - "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDGdByTgSVHq......."
    - name: elroy
      password_hash: "$6$5s2u6/jR$un0AvWnqilcgaNB3Mkxd5yYv6mTlWfOoCYHZmfi3LDKVltj.E8XNKEcwWm..."
      ssh_authorized_keys:
        - "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDGdByTgSVHq......."
      groups: [ sudo, docker ]

As you can see from this snippet, the core user is modified with a private SSH key, and a new user named elroy is added. The elroy user can log in with a private SSH key or with a password and is added to the sudo and docker groups.