ansible-podman/roles/service/meta/argument_specs.yaml

---
argument_specs:
  main:
    description: Sets up a service in podman container(s)
    options:
      service_name:
        description: Name of the service.
        type: str
        required: true

      service_domains:
        description: A list of domains which should be proxied to the main service container
        type: list
        required: false
        default: []
        elements: str
      service_container_http_port:
        description:
          - Port inside the container where http requests will be proxied to.
          - Required if service_domains is not empty.
        type: int
        required: false
      service_proxy_pass_host_header:
        description: Passed to vhost role as vhost_proxy_pass_header
        type: bool
        required: false
        default: true
      service_vhost_locations:
        description: Passed to vhost role as vhost_locations
        type: list
        required: false
        default: []

      service_container_image:
        description: "The image to run in the service container(s), in FQIN format (registry/imagename:tag)."
        type: str
        required: true
      service_container_image_creds:
        description: Credentials used to authenticate with the registry
        type: dict
        required: false
        default:
          username: ""
          password: ""
        options:
          username:
            description: Username
            type: str
            required: true
          password:
            description: Password
            type: str
            required: true

      service_container_user:
        description: The UID to run as inside the container
        type: str
        required: false
        default: ""
      service_container_additional_networks:
        description: A list of additional podman networks for the service container (in addition to service name network).
        type: list
        required: false
        default: []
        elements: str
      service_container_publish_ports:
        description: "A list of published ports in docker format (<host listen address>:<host port>:<container port>)"
        type: list
        required: false
        default: []
        elements: str
      service_container_mounts:
        description: List of bind mounts or volumes to be mounted inside the service container(s).
        type: list
        required: false
        default: []
        elements: dict
        options:
          type:
            description: Type of volume
            type: str
            required: true
            choices:
              - volume
              - bind
              - template
          source:
            description:
              - Mount source.
              - If mount type is volume, name of the volume.
              - If mount type is bind, host path to bind mount inside the container.
              - If mount type is template, the name of the template file, must end in .j2
            type: str
            required: true
          destination:
            description: Path inside the container to mount at
            type: str
            required: true
          readonly:
            description:
              - If true, volume will be mounted as read only inside the container.
              - Defaults to false for volume and bind, true for template
            type: bool
            required: false
          user:
            description: Volume owner uid. Only applicable if mount type is volume.
            type: str
            required: false
            default: ""
          group:
            description: Volume owner gid. Only applicable if mount type is volume.
            type: str
            required: false
            default: ""
      service_container_secrets:
        description:
          - >
            A list of secrets available to the service container as file or environment variable
          - >
            A dict of secrets and their values (including autogenerated values) is available as
            `service_podman_secrets` for use in templates. This should only be used if the
            container doesn't support reading the secret from file or environment variable.
        type: list
        required: false
        default: []
        elements: dict
        options:
          name:
            description: Name of the secret
            type: str
            required: true
          value:
            description:
              - >
                Value of the secret. Defaults to a 128-character random string containing
                alphanumeric characters.
              - >
                If the value is not explicitly set, it will not be changed if the secret
                already exists.
            type: str
            required: false
          length:
            description: Length of randomly generated string
            type: int
            required: false
            default: 128
          type:
            description: How the secret will be exposed to the container
            type: str
            choices:
              - mount
              - env
            default: mount
          target:
            description: >
              Where the secret will be available inside the container. If type is mount, this is
              either a full file path or a filename under /run/secrets. If type is env, this is
              the name of the environment variable. Defaults to secret name.
            type: str
            required: false

      service_container_env:
        description: A dict of environment variables for the service container(s)
        type: dict
        required: false
        default: {}

      service_database_type:
        description:
          - Database type to set up.
          - >
            It will be run in a docker container accessible to the service at
            host {{ service_name }}-{{ service_database_type }} on the default port.
          - The database user will be {{ service_name }}
          - The password will be accessible as secret at /run/secrets/{{ service_name }}-{{ service_database_type }}
          - >
            The password will also be available as the
            service_podman_secrets['{{ service_name }}-{{ service_database_type }}'] variable.
        type: str
        required: false
        choices:
          - postgres
          - none
        default: none
      service_postgres_tag:
        description:
          - Postgresql version to use.
          - Can be debian (n) or alpine-based (n-alpine), where n can be major version like 14 or minor like 14.13.
          - Required if service_database_type is postgres, does nothing otherwise
        type: str
        required: false

      service_additional_containers:
        description:
          - List of additional containers for the sercice.
          - >
            Will inherit most options from main service container, except for publish_ports.
            All options can be overridden per-container.
        type: list
        required: false
        default: []
        elements: dict
        options:
          name:
            description:
              - Name of the container.
              - >
                This will be appended to the service name, so if for example service name is
                nextcloud and this variable is cron, the resulting container will be called
                nextcloud-cron
            type: str
            required: true
          image:
            description: "The image to run in the container, in FQIN format (registry/image:tag)"
            type: str
            required: false
            default: "{{ service_container_image }}"
          mounts:
            description: List of bind mounts or volumes to be mounted inside the main service container.
            type: list
            required: false
            default: "{{ service_container_mounts }}"
            elements: dict
            options:
              type:
                description: Type of volume
                type: str
                required: true
                choices:
                  - volume
                  - bind
                  - template
              source:
                description:
                  - Mount source.
                  - If mount type is volume, name of the volume.
                  - If mount type is bind, host path to bind mount inside the container.
                  - If mount type is template, the name of the template file, must end in .j2
                type: str
                required: true
              destination:
                description: Path inside the container to mount at
                type: str
                required: true
              readonly:
                description:
                  - If true, volume will be mounted as read only inside the container
                  - Defaults to false for volume and bind, true for template
                type: bool
                required: false
          publish_ports:
            description: "A list of published ports in docker format (<host listen address>:<host port>:<container port>)"
            type: list
            required: false
            default: []
            elements: str
          env:
            description: A dict of environment variables for the container
            type: dict
            required: false
            default: {}

      service_requires:
        description: List of systemd units this service container depends on.
        type: list
        required: false
        default: []
        elements: str
      service_wants:
        description: List of systemd units this service container weakly depends on.
        type: list
        required: false
        default: []
        elements: str
      service_auto_update:
        description: Whether to let podman automatically update the service containers whenever the specified image gets updated
        type: bool
        required: false
        default: true