Skip to main content

Configuration

e.g.

registries:
- type: standard
  ref: v4.155.1 # renovate: depName=aquaproj/aqua-registry

packages:
- name: helm/helm@v3.7.0
- name: golangci/golangci-lint@v1.42.1
- import: aqua/*.yaml

Configuration File Path​

aqua searches the following configuration files.

  1. --config (-c) option (environment variable AQUA_CONFIG
  2. \.?aqua\.ya?ml or \.?aqua/aqua\.ya?ml from the current directory to the root directory. If configuration files are found in the multiple directories, aqua read all of them
  3. global configuration: environment variable AQUA_GLOBAL_CONFIG

To install tools in global configuration files, you have to set -a to aqua install command.

info

From aqua v1.33.0, aqua supports keeping aqua's configuration files in one directory .?aqua.

Environment variables​

$ env AQUA_GENERATE_WITH_DETAIL=true aqua g cli/cli
- name: cli/cli@v2.2.0
  description: GitHub’s official command line tool
  link: https://github.com/cli/cli

JSON Schema​

Input Complementation by YAML Language Server​

Add a code comment to aqua.yaml:

# yaml-language-server: $schema=https://raw.githubusercontent.com/aquaproj/aqua/main/json-schema/aqua-yaml.json

If you specify a branch like main as version, editors can't reflect the update of JSON Schema well as they cache JSON Schema. You would need to do something like reopening the file. So it's good to specify semver and update it periodically.

# yaml-language-server: $schema=https://raw.githubusercontent.com/aquaproj/aqua/v2.40.0/json-schema/aqua-yaml.json

Using Renovate and our Renovate Config Preset, you can automate the update:

{
  "extends": [
    "github>suzuki-shunsuke/renovate-config:yaml-language-server#3.0.0"
  ]
}

e.g. https://github.com/aquaproj/aqua-installer/pull/735

Configuration attributes​

caution

inline_registry was removed from aqua >= v0.9.0. Please use local registry.

registries​

e.g.

registries:
- type: standard
  ref: v4.155.1 # renovate: depName=aquaproj/aqua-registry

Registry types

standard registry​

e.g.

registries:
- type: standard
  ref: v4.155.1 # renovate: depName=aquaproj/aqua-registry
  • ref: the Registry Version. Please check Releases

This is equivalent to the following definition.

registries:
- name: standard
  type: github_content
  repo_owner: aquaproj
  repo_name: aqua-registry
  ref: v4.155.1 # renovate: depName=aquaproj/aqua-registry
  path: registry.yaml

You can also specify a commit hash as ref.

registries:
- type: standard
  ref: 0d1572334a460e5a74f2a6455e510d8a4d6c8e93
caution

Don't specify a branch name as ref, because aqua treats the ref as immutable.

registries:
- type: standard
  ref: main # Specify a tag or commit hash

local registry​

e.g.

registries:
- name: local
  type: local
  path: registry.yaml
- name: home
  type: local
  path: $HOME/aqua-registry.yaml
  • name: Registry name
  • path: The file path. Either absolute path or relative path from aqua.yaml. If path starts with $HOME + OS specific path separator such as '/', it's replaced with the home directory path

Please see Configuration (registry.yaml).

github_content registry​

e.g.

registries:
- name: foo
  type: github_content
  repo_owner: aquaproj
  repo_name: aqua-registry
  ref: v4.155.1 # renovate: depName=aquaproj/aqua-registry
  path: registry.yaml
  • name: Registry Name
  • repo_owner: Repository Owner name
  • repo_name: Repository name
  • ref: Repository tag or commit hash. Don't specify a branch name as ref, because aqua treats the ref as immutable
  • path: file path from the repository root directory

packages​

e.g.

packages:
- name: helm/helm
  version: v3.7.0 # renovate: depName=helm/helm
- name: golangci/golangci-lint@v1.42.1
  registry: standard
  • name: (string, optional) package name. If import isn't set, this is required
    • format: <package name>[@<package version>]
  • registry: (string, optional) registry name
    • default value is standard
  • version: (string, optional) package version
  • go_version_file: (string, optional) aqua >= v2.28.0 #2632 A file path to go.mod or go.work. This field is used to get the version of go from go directive in go.mod or go.work
  • version_expr: (string, optional) aqua >= v2.40.0 Please see here for details
  • version_expr_prefix: (string, optional) aqua >= v2.40.0 Please see here for details
  • import: (string, optional) glob pattern of package files. This is relative path from the configuration file. This is parsed with filepath.Glob. Please see Split the list of packages too.
  • tags: Filter installed packages. Please see Filter packages with tags
  • update: The setting for aqua update command
    • update.enabled: If this is false, aqua update command ignores the package. If the package name is passed to aqua up command explicitly, enabled is ignored. By default, enabled is true.
  • vars: (map of string) v2.31.0 #3052. Please see here
  • command_aliases: (array of objects, optional) v2.37.0 #3224: Aliases of commands. Please see here

The following two configuration is equivalent.

- name: golangci/golangci-lint@v1.42.1
  registry: standard
- name: golangci/golangci-lint
  registry: standard
  version: v1.42.1

When you want to update the package with Renovate, the first style is better because you don't have to write code comments for Renovate's Regex Manager.

- name: golangci/golangci-lint
  registry: standard
  version: v1.43.0 # renovate: depName=golangci/golangci-lint

If the package name in the code comment is wrong, the package version is changed wrongly.

- name: golangci/golangci-lint
  registry: standard
  # depName is wrong!
  version: v1.42.1 # renovate: depName=helm/helm

On the other hand, you can prevent such a miss configuration by the first style.