sources/api/openapi.yaml

openapi: "3.0.2"
info:
  version: "0.1.0"
  title: "Bottlerocket API"
  description: "The API for the Bottlerocket OS"
  license:
    name: "Apache-2.0 OR MIT"
    url: "https://github.com/bottlerocket-os/bottlerocket/blob/develop/COPYRIGHT"

servers:
- url: file:///run/api.sock
  description: The production API server

components:
  schemas:
    HashMap:
      type: object
      additionalProperties:
        type: string
    Service:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/HashMap'
    Services:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/Service'
    ConfigurationFileInfo:
      type: object
      properties:
        template-path:
          type: string
        path:
          type: string
        mode:
          type: string
    ConfigurationFiles:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/ConfigurationFileInfo'
    Report:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
    Version:
      type: object
      properties:
        major:
          type: integer
        minor:
          type: integer
        patch:
          type: integer
    UpdateImage:
      type: object
      properties:
        arch:
          type: string
        variant:
          type: string
        version:
          $ref: '#/components/schemas/Version'
    StagedImage:
      type: object
      properties:
        image:
          $ref: '#/components/schemas/UpdateImage'
        next_to_boot:
          type: boolean
    CommandResult:
      type: object
      properties:
        cmd_type:
          type: string
        cmd_status:
          type: string
        timestamp:
          type: string
        exit_status:
          type: integer
        stderr:
          type: string
    UpdateStatus:
      type: object
      properties:
        update_state:
          type: string
        available_updates:
          type: array
          items:
            $ref: '#/components/schemas/Version'
        chosen-update:
          $ref: '#/components/schemas/UpdateImage'
        active-partition:
          $ref: '#/components/schemas/StagedImage'
        staging-partition:
          $ref: '#/components/schemas/StagedImage'
        most-recent-command:
          $ref: '#/components/schemas/CommandResult'
    SettingsKeyPair:
      type: object
      properties:
        request_payload:
          type: string
    Settings:
      type: object
      properties:
        motd:
          type: string
        kubernetes:
          type: object
        ecs:
          type: object
        updates:
          type: object
        host-containers:
          type: object
        ntp:
          type: object
          properties:
            time-servers:
              type: array
              items:
                type: string
            options:
              type: array
              items:
                type: string
        SettingsResponseWithMetadata:
          type: object
          properties:
            settings:
              $ref: '#/components/schemas/Settings'
            metadata:
              $ref: '#/components/schemas/HashMap'
        network:
          type: object
          properties:
            hostname:
              type: string
        kernel:
          type: object
          properties:
            lockdown:
              type: string
        aws:
          type: object
          properties:
          region:
            type: string
          config:
            type: string
          credentials:
            type: string
          profile:
            type: string
        metrics:
          type: object
        oci-defaults:
          type: object
        oci-hooks:
          type: object
          properties:
            log4j-hotpatch-enabled:
              type: boolean
        cloudformation:
          type: object
          properties:
            should-signal:
              type: boolean
            stack-name:
              type: string
            logical-resource-id:
              type: string
        autoscaling:
          type: object
          properties:
            should-wait:
              type: boolean
      additionalProperties: true
    BottlerocketRelease:
      type: object
      properties:
        pretty-name:
          type: string
        variant-id:
          type: string
        version-id:
          type: string
        build-id:
          type: string
        arch:
          type: string
    Model:
      type: object
      properties:
        settings:
          $ref: '#/components/schemas/Settings'
        services:
          $ref: '#/components/schemas/Services'
        configuration-files:
          $ref: '#/components/schemas/ConfigurationFiles'
        os:
          $ref: '#/components/schemas/BottlerocketRelease'
    EphemeralStorageInit:
      type: object
      properties:
        filesystem:
          type: string
        disks:
          type: array
    EphemeralStorageBind:
      type: object
      properties:
        targets:
          type: array
    SettingGenerators:
      type: object
      additionalProperties:
        oneOf:
        - type: string
        - type: object
          additionalProperties: false
          properties:
            command:
              type: string
            strength:
              enum:
              - weak
              - strong
              type: string
          required:
          - command
paths:
  /:
    get:
      summary: "Get current model, including settings, services, configuration files, and os info"
      operationId: "get_model"
      parameters:
        - in: query
          name: prefix
          description: "Specific key prefix to query"
          schema:
            type: string
          required: false
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Model"
        500:
          description: "Server error"

  /settings:
    get:
      summary: "Get current settings"
      operationId: "get_settings"
      parameters:
        - in: query
          name: keys
          description: "Specific keys to query. Takes precedence over 'prefix' if both query parameters are supplied"
          schema:
            type: array
            items:
              type: string
          # `style: form` and `explode: false` format parameters as such:  /settings?keys=foo,bar,baz
          style: form
          explode: false
          required: false
        - in: query
          name: prefix
          description: "Specific key prefix to query. This parameter will be ignored if 'keys' is also supplied"
          schema:
            type: string
          required: false
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Settings"
        500:
          description: "Server error"
    patch:
      summary: "Update settings"
      operationId: "set_settings"
      parameters:
        - in: query
          name: tx
          description: "Transaction in which to update settings; defaults to user 'default' transaction"
          schema:
            type: string
          required: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Settings"
      responses:
        204:
          description: "Settings successfully staged for update"
        400:
          description: "Invalid body"
        500:
          description: "Server error"
  /settings/keypair/:
    patch:
      summary: "Update settings which come in key value form"
      operationId: "set_key_pair_settings"
      parameters:
        - in: query
          name: tx
          description: "Transaction in which to update settings; defaults to user 'default' transaction"
          schema:
            type: string
          required: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SettingsKeyPair"
      responses:
        204:
          description: "Settings successfully staged for update"
        400:
          description: "Invalid body"
        500:
          description: "Server error"
  /tx:
    get:
      summary: "Get pending settings in a transaction"
      operationId: "get_tx"
      parameters:
        - in: query
          name: tx
          description: "Transaction for which to retrieve pending settings; defaults to user 'default' transaction"
          schema:
            type: string
          required: false
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              schema:
                $ref: #/components/schemas/Settings"
        500:
          description: "Server error"
    delete:
      summary: "Delete transaction"
      operationId: "delete_tx"
      parameters:
        - in: query
          name: tx
          description: "Transaction to delete; defaults to user 'default' transaction"
          schema:
            type: string
          required: false
      responses:
        200:
          description: "Successful deleted pending settings - deleted keys are returned"
        500:
          description: "Server error"
  
  /v2/tx:
    get:
      summary: "Get pending settings and metadata in a transaction"
      operationId: "get_tx_v2"
      parameters:
        - in: query
          name: tx
          description: "Transaction to retrieve pending settings and metadata; defaults to user 'default' transaction"
          schema:
            type: string
          required: false
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              schema:
                $ref: #/components/schemas/SettingsResponseWithMetadata"
        500:
          description: "Server error"

  /tx/list:
    get:
      summary: "List names of pending transactions"
      operationId: "list_tx"
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        500:
          description: "Server error"

  /tx/commit:
    post:
      summary: "Commit pending settings, without applying changes to config files or restarting services"
      operationId: "commit_tx"
      parameters:
        - in: query
          name: tx
          description: "Transaction to commit; defaults to user 'default' transaction"
          schema:
            type: string
          required: false
      responses:
        200:
          description: "Successfully Staged settings - changed keys are returned"
        500:
          description: "Server error"

  /tx/apply:
    post:
      summary: "Apply changes to config files and restart services"
      operationId: "apply"
      parameters:
        - in: query
          name: keys
          description: "Apply changes only if related to these keys; if not specified, applies for all known keys"
          schema:
            type: array
            items:
              type: string
          # `style: form` and `explode: false` format parameters as such:  /tx/apply?keys=settings.foo,settings.bar
          style: form
          explode: false
          required: false
      responses:
        204:
          description: "Successfully started settings applier"
        500:
          description: "Server error"

  /tx/commit_and_apply:
    post:
      summary: "Commit transaction, and apply any committed changes to relevant config files and services"
      operationId: "commit_tx_and_apply"
      parameters:
        - in: query
          name: tx
          description: "Transaction to commit; defaults to user 'default' transaction"
          schema:
            type: string
          required: false
      responses:
        200:
          description: "Successful settings update, committed keys are returned"
        500:
          description: "Server error"

  /os:
    get:
      summary: "Get OS information such as version, variant, and architecture"
      operationId: "get_os_info"
      parameters:
        - in: query
          name: prefix
          description: "Specific key prefix to query"
          schema:
            type: string
          required: false
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              # The response is a hashmap of string to string. Example:
              # { "arch": "x86_64" }
              schema:
                type: object
                additionalProperties:
                  type: string
        500:
          description: "Server error"

  /metadata/affected-services:
    get:
      summary: "Get affected services"
      operationId: "get_affected_services"
      parameters:
        - in: query
          name: keys
          description: "Specific keys to query"
          schema:
            type: array
            items:
              type: string
          # `style: form` and `explode: false` format parameters as such:  /metadata/affected-services?keys=settings.foo,settings.bar
          style: form
          explode: false
          required: true
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              # The response is a hashmap of string to array of strings. Example:
              # { "settings.foo": [ "service1", "service2" ] }
              schema:
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: string
        400:
          description: "Missing required query parameter: 'keys'"
        500:
          description: "Server error"

  /metadata/setting-generators:
    get:
      summary: "Get programs needed to generate settings"
      operationId: "get_setting_generators"
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              # The response is a hashmap of string to string. Example:
              # { "settings.foobar": "/usr/bin/foobar" }
              schema:
                type: object
                additionalProperties:
                  type: string
        500:
          description: "Server error"
  /v2/metadata/setting-generators:
    get:
      summary: "Get programs to generate settings, and the strength of the generated settings"
      operationId: "get_setting_generators_v2"
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              # The response is a hashmap of string to Object. Example:
              # { "settings.foobar": "/usr/bin/foobar" } or 
              # { "settings.foobar": {
              #     "command": "/usr/bin/foobar",
              #     "strength": "weak"
              #    } 
              # }
              schema:
                $ref: "#/components/schemas/SettingGenerators"
        500:
          description: "Server error"

  /metadata/templates:
    get:
      summary: "Get template strings for dynamically generated settings"
      operationId: "get_templates"
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              # The response is a hashmap of string to string. Example:
              # { "settings.foobar": "hi {{ key }}" }
              schema:
                type: object
                additionalProperties:
                  type: string
        500:
          description: "Server error"

  /services:
    get:
      summary: "Get service data"
      operationId: "get_services"
      parameters:
        - in: query
          name: names
          description: "Specific services to query"
          schema:
            type: array
            items:
              type: string
          # `style: form` and `explode: false` format parameters as such:  /services?names=foo,bar,baz
          style: form
          explode: false
          required: false
        - in: query
          name: prefix
          description: "Specific key prefix to query. This parameter will be ignored if 'names' is also supplied"
          schema:
            type: string
          required: false
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Services"
        500:
          description: "Server error"

  /configuration-files:
    get:
      summary: "Get configuration file data"
      operationId: "get_config_files"
      parameters:
        - in: query
          name: names
          description: "Specific configuration files to query"
          schema:
            type: array
            items:
              type: string
          # `style: form` and `explode: false` format parameters as such:  /configuration-files?names=file1,file2
          style: form
          explode: false
          required: false
        - in: query
          name: prefix
          description: "Specific key prefix to query. This parameter will be ignored if 'names' is also supplied"
          schema:
            type: string
          required: false
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConfigurationFiles"
        500:
          description: "Server error"

  /actions/reboot:
    post:
      summary: "Reboot"
      operationId: "reboot"
      responses:
        204:
          description: "Reboot requested"
        500:
          description: "Server error"

  /actions/refresh-updates:
    post:
      summary: "Query update repository and refresh list of updates"
      operationId: "refresh_update"
      responses:
        204:
          description: "Successful request"
        500:
          description: "Server error"
        423:
          description: "Update write lock held. Try again in a moment"

  /actions/prepare-update:
    post:
      summary: "Download the chosen update and write the update image to the inactive partition"
      operationId: "prepare_update"
      responses:
        204:
          description: "Successful request"
        404:
          description: "Chosen update does not exist"
        409:
          description: "Action not allowed according to current update state"
        500:
          description: "Server error"
        423:
          description: "Update write lock held. Try again in a moment"

  /actions/activate-update:
    post:
      summary: "Mark the partition with the prepared update as active so you can reboot into the chosen version"
      operationId: "activate_update"
      responses:
        204:
          description: "Successfully activated update"
        404:
          description: "No update image applied to staging partition, need to prepare-update first"
        409:
          description: "Action not allowed according to current update state"
        500:
          description: "Server error"
        423:
          description: "Update write lock held. Try again in a moment"

  /actions/deactivate-update:
    post:
      summary: "Deactivate the update by marking the running partition as active again"
      operationId: "deactivate-update"
      responses:
        204:
          description: "Successfully deactivated update"
        404:
          description: "No update image applied to staging partition, need to prepare-update first"
        409:
          description: "Action not allowed according to current update state"
        500:
          description: "Server error"
        423:
          description: "Update write lock held. Try again in a moment"

  /updates/status:
    get:
      summary: "Get update status"
      operationId: "get_update_status"
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UpdateStatus"
        500:
          description: "Server error"
        423:
          description: "Update write lock held. Try again in a moment"

  /exec:
    get:
      summary: "Request exec WebSocket"
      operationId: "exec"
      responses:
        101:
          description: "Connection upgraded to WebSocket"
        500:
          description: "Server error"

  /report:
    get:
      summary: "Get available report types"
      operationId: "get_reports"
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Report"
        500:
          description: "Server error"

  /report/cis:
    get:
      summary: "Get CIS benchmark report"
      operationId: "cis-report"
      parameters:
        - in: query
          name: level
          description: "The CIS compliance level to test (1 or 2). Default level is 1."
          schema:
            type: integer
            minimum: 1
            maximum: 2
          required: false
        - in: query
          name: format
          description: "The CIS compliance report format (text or json). Default format is text."
          schema:
            type: string
          required: false
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              schema:
                type: string
        400:
          description: "Bad request input"
        422:
          description: "Unprocessable request"
        500:
          description: "Server error"

  /report/fips:
    get:
      summary: "Get FIPS Security Policy report"
      operationId: "fips-report"
      parameters:
        - in: query
          name: format
          description: "The FIPS Security Policy report format (text or json). Default format is text."
          schema:
            type: string
          required: false
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              schema:
                type: string
        400:
          description: "Bad request input"
        422:
          description: "Unprocessable request"
        500:
          description: "Server error"
  /ephemeral-storage/init:
    post:
      summary: "Initialize ephemeral storage"
      operationId: "init"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EphemeralStorageInit"
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              schema:
                type: string
        400:
          description: "Bad request input"
        422:
          description: "Unprocessable request"
        500:
          description: "Server error"
  /ephemeral-storage/bind:
    post:
      summary: "Bind directories to previously initialized ephemeral storage"
      operationId: "bind"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EphemeralStorageBind"
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              schema:
                type: string
        400:
          description: "Bad request input"
        422:
          description: "Unprocessable request"
        500:
          description: "Server error"
  /ephemeral-storage/list-disks:
    get:
      summary: "List the discovered ephemeral disks that can be initialized"
      operationId: "list-disks"
      parameters:
        - in: query
          name: format
          description: "Format of the disk listing (text or json). Default format is text."
          schema:
            type: string
          required: false
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              schema:
                type: string
        400:
          description: "Bad request input"
        422:
          description: "Unprocessable request"
        500:
          description: "Server error"
  /ephemeral-storage/list-dirs:
    get:
      summary: "List the directories that can be bound to ephemeral storage"
      operationId: "list-dirs"
      parameters:
        - in: query
          name: format
          description: "Format of the directory listing (text or json). Default format is text."
          schema:
            type: string
          required: false
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              schema:
                type: string
        400:
          description: "Bad request input"
        422:
          description: "Unprocessable request"
        500:
          description: "Server error"