Welcome to ibmvia-autoconf documentation!

ibmvia-autoconf is an automation layer written on top of pyIVIA. This library should be used to apply YAML configuration files to a Verify Identity Access deployment.

This library is designed to work with both Appliance and Container based deployments, and is not idempotent.

Configuration is supplied in YAML syntax using a well-defined data structure (detailed in this doc).

Installation

You can install ibmvia-autoconf with pip:

$ pip install ibmvia-autoconf

Architecture

Users should take care to ensure the configuration of these separate features are compatible (eg. conflicting ALC’s in a WebSEAL reverse proxy). Administrators will also have to define the webseal.runtime entry for many configuration options even if the WebSEAL Runtime Component is already configured.

Example configurations can be found in the examples directory with additional documentation in the Examples / Getting Started page.

Modules

The configuration process is broken into six modules. Each module is responsible for configuring a subset of Verify Identity Access features. The order of configuration is:

  • base (Licensing, SSL Databases, Cluster Settings)

  • appliance (if applicable)

  • container (if applicable)

  • webseal

  • access control

  • federations

More complex deployment architectures can be achieved by running sequential config.yaml descriptors.

YAML configuration keywords

Each module expects a YAML object describing the desired configuration state. There are a number of useful features which can be used to make configuration files re-usable and version controlled. There are three keywords which can be used in configuration files:

  • !include

    Used to include a YAML configuration file as the value of the given key. This file can be either an absolute path or relative to the IVIA_CONFIG_BASE environment variable. eg:

    container: !include base_config.yaml
webseal: !include webseal.yaml
access_control: !include aac.yaml
  • !secret

    Used to set the value of the given key as a value read from the given Kubernetes Secret Namespace/Name, eg:

    admin_password: !secret default/isva-secrets:admin_secret
  • !environment:

    Used to set the value of the given key as the value read from the given environment variable, eg:

    admin_password: !environment IVIA_ADMIN_SECRET

Environment properties

In addition to the supplied YAML configuration, some properties can alternatively be set as environment variables. If these variables are set, they take priority over values set in configuration files.

  • IVIA_CONFIG_BASE

    This variable is the root directory of all configuration files for the given Verify Identity Access Deployment. This can include: YAML configuration files; HTML template pages; JavaScript mapping rules; XML configuration files.

    Note

    If this environment variable is not set then the user’s $HOME directory is used.

  • IVIA_CONFIG_YAML

    This variable defines the YAML configuration file to deploy. This can be either relative to the IVIA_CONFIG_BASE directory or an absolute file path. If this variable is not defined then the configuration will look for a file called config.yaml in the IVIA_CONFIG_BASE directory.

  • IVIA_MGMT_BASE_URL

    This variable is the URL address that Verify Identity Access Local Management Interface is responding on. This should contain: the https scheme; the domain or IP address; and a port if not the standard (443) port. eg: https://127.0.0.2:9443.

  • IVIA_MGMT_USER

    The user to perform configuration as. This user should have sufficient permissions to configure all of the features in your YAML configuration file.

  • IVIA_MGMT_PWD

    The password required to authenticate as the user defined by IVIA_MGMT_USER.

  • IVIA_MGMT_OLD_PWD

    If a password change is required then this variable defines the password for IVIA_MGMT_USER before the configuration is applied.

  • IVIA_KUBERNETES_YAML_CONFIG

    This variable defines the Kubernetes cluster configuration file required to run kubectl commands. This configuration file should have sufficient permission in your cluster to restart deployments and pods in the namespace that Verify Identity Access is deployed to. The file path can either be absolute or relative to the IVIA_CONFIG_BASE variable.

    Note

    This is only applicable for Container deployments using Kubernetes orchestration.

  • IVIA_DOCKER_COMPOSE_CONFIG

    This variable defines the Docker-Compose deployment configuration file required to run docker-compose commands for your Verify Identity Access deployment. This file path can either be absolute or relative to the IVIA_CONFIG_BASE variable.

    Note

    This is only applicable for Container deployments using Docker-Compose orchestration.

  • IVIA_CONFIGURATOR_LOG_LEVEL

    This variable set the logging level for the autoconf tool. The default log level is INFO.

Detailed information on configuration object structure can be found in the submodule documentation

Contents:

Indices and tables