Create, edit, and delete a Module

This page outlines how to:

• Create Modules
• Edit Modules
• Delete Modules

Create a Module

Prerequisites

You should download and configure the Apollo CLI before creating a Module.

This guide will walk through creating a new Module that contains Products related to an application control plane.

Create the Module YAML file

To create a new Module, create a YAML file that contains configuration for the Module. The name of the file should be the same as the value in the name field. In this example, the file name would be control-plane-module.yaml.

Name and description

Copied!
1
2
3
name: "control-plane-module"
displayName: "Control Plane Module"
description: "Entities required for the application control plane."

Variables

You can define any variables for the Module in the variables block of Module YAML file. For each variable, you should define the following configuration items:

• Name: The name for the variable, for example releaseChannel.
• type: The type of value a user should enter when installing a Module. Currently, string is the only supported type.
• defaultValue (optional): Default value for the variable when installing a Module. If no default value is present, then you must enter a value when installing the Module.
• description: A description for the variable, which will provide guidance to you when you are installing the Module.

Below is an example variable definition:

Copied!
1
2
3
4
5
6
variables:
  releaseChannel:
    type: string,
    string:
      defaultValue: "STABLE_2",
      description: "Default Release Channel for all Entities"

Entities

You can define specific configuration for each Entity of the Module in the entities block in the Module YAML file.

Note that when you refer to a variable, the value should be surrounded by double curly brackets and should include the moduleVariable prefix before the variable name. For example, you can refer to the releaseChannel variable by writing {{moduleVariable.releaseChannel}}. For each Entity, you should define the following configuration items:

• type: The Product type of the Entity. Currently, only Helm charts are supported.
• productId: The Product ID of the Entity, which is the groupId:artifactId of the Product's Maven coordinate.
• entityName (optional): An identifier for the Entity. Defaults to the artifactId from the Entity's ProductId.
• releaseChannel (optional): The Release Channel that the Entity should follow. Defaults to the Environment's Release Channel.
• k8sNamespace: The Kubernetes namespace that the Entity should be installed in.
• ignoredDependencies: Apollo will ignore any Product dependency constraints for the Products you list in the ignored dependencies. If there are none, you should enter an empty list like the below example.
• downtimeMaintenanceWindowId (optional): You can specify all-time, or use a variable to specify a maintenance window at Module installation. Defaults to the Environment's default downtime maintenance window.
• noDowntimeMaintenanceWindowId (optional): You can specify all-time, or use a variable to specify a maintenance window at Module installation. Defaults to the Environment's default no-downtime maintenance window.
• configOverrides (optional): You can define Entity config overrides in the Module YAML file.
• syncConfigOverrides (optional): Determines whether Apollo should overwrite existing config overrides for an Entity or not when installing a Module or updating an existing Module installation. When set to ENABLED, Apollo will overwrite existing config overrides for the Entity. When set to DISABLED, Apollo will not overwrite existing config overrides for the Entity. With both options, when adding a new Entity, Apollo will add the config overrides specified in the definition regardless. Defaults to ENABLED.
• markedForUninstallation (optional): If this field is present, Apollo will mark the Entity for uninstallation when the Module is installed. If the Entity does not exist in the Environment, Apollo will ignore this Entity during Module installation.
  • minVersion (optional): The minimum version of the Entity that should be uninstalled. If not present, Apollo will uninstall all versions of the Entity.
  • unmanageAfterUninstall (optional): If set to AUTOMATIC, Apollo will unmanage the Entity after uninstalling it. If set to MANUAL, Apollo will leave the Entity managed after uninstalling it. Defaults to AUTOMATIC.
• secretRequirements (optional): You can specify a list of secret names and list of associated secret keys that must exist before the Module is installed or upgraded. The Module installation interface will guide users through setting up the correct secrets for the Entities that have this field set. See the full example below for the syntax of secret requirements.

All non-optional fields must be present for each Entity in the Module YAML file. If you do not know a particular value when creating a Module, you can use a variable to define the value at Module installation.

Below is an example Entity definition:

Copied!
1
2
3
4
5
6
7
8
9
10
entities:
  - type: helmChart
    helmChart:
      productId: com.palantir.example:backend-service
      releaseChannel: "{{moduleVariable.releaseChannel}}"
      k8sNamespace: app-namespace
      configOverrides: |
        2.0.0:
          overrides:
            num-threads: 100

Full example

Below is an example of a complete Module YAML file. You can add more variables and Entities using a comma separated list of entries.

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
name: control-plane-module
displayName: Control Plane Module
description: Entities required for the application control plane.
variables:
  releaseChannel:
    type: string
    string:
      defaultValue: STABLE_2
      description: Default Release Channel for all Entities
entities:
  - type: helmChart
    helmChart:
      productId: com.palantir.example:backend-service
      releaseChannel: "{{moduleVariable.releaseChannel}}"
      k8sNamespace: app-namespace
      configOverrides: |
        2.0.0:
          overrides:
            num-threads: 100
  - type: helmChart
    helmChart:
      productId: com.palantir.example:frontend-application
      releaseChannel: "{{moduleVariable.releaseChannel}}"
      k8sNamespace: app-namespace
      downtimeMaintenanceWindowId: all-time
      noDowntimeMaintenanceWindowId: all-time
      secretRequirements:
        my-secret:
          - type: multikey
            multikey:
              description: API key for communicating between services
              keys:
                - api-key
  - type: helmChart
    helmChart:
        productId: com.palantir.example:deprecated-application
        k8sNamespace: app-namespace
        markedForUninstallation:
            minVersion: 1.0.0
            unmanageAfterUninstall: MANUAL

Publish the Module to Apollo

Run the following command in your terminal to publish your Module to Apollo.

apollo-cli create-module --module-definition-file path-to-yaml-file

Learn more about the apollo-cli create-module command.

View your Module

You can confirm that your Module was published in the Modules tab of the Software Catalog.

Edit a Module

You can edit a Module by publishing a new version of the Module YAML file. To download the Module YAML file, navigate to the Module overview page and select Edit module from the Actions dropdown.

This will open a dialog where you can select Download module definition.

You can edit the Module YAML file and publish it to Apollo using the Apollo CLI.

Once the new version of the Module is published you can view it in the version selector next to the Module name.

You can also view the version of each Module installation in the Module installations table.

Note that Module versions are immutable. In addition, when a new version of a Module is published, Apollo will attempt to update existing Module installations to the latest version of the Module by proposing a change request.

Evolving a Module

When publishing a new version of a Module, you should consider how the changes will impact existing installations of the Module. Environment editors should ensure that updates to their Modules installations are backwards compatible. For example, if you want to uninstall an Entity in a Module from all Environments where the Module is installed, you should mark the Entity for uninstallation in the Module definition. This will ensure that the Entity is removed from the Environment when the Module is updated. If you simply remove the Entity from the Module definition, the Entity will not be uninstalled from the Environment when the Module is updated, and the Entity will remain installed in the Environment.

Managing config overrides with Modules

Modules provide a way to manage config overrides for Entities in Apollo across multiple Environments. When you define an Entity in a Module, you can specify config overrides for the Entity in the configOverrides field. You can use variables to add flexibility to the config overrides of an Entity. The example below shows the config overrides for an Entity in a Module that defines a variable enableFeatureFlag:

Copied!
1
2
3
2.0.0:
  overrides:
    my-feature-flag: {{ moduleVariable.enableFeatureFlag }}

When installing the Module, you will be prompted to provide a value for the variable. You can also decide to use the default if specified in the Module definition.

By default, Apollo will overwrite existing config overrides for an Entity when installing or updating a Module installation. This allows you to reduce config overrides divergence across Environments where the Module is installed. You should use variables to handle cases where specific values in the config overrides are expected to be different across Environments.

You can opt out of this default behaviour for a specific Entity by disabling config overrides syncing by setting syncConfigOverrides to DISABLED in the Module definition. In this case, Apollo will still add the config overrides specified in the definition when adding a new Entity, but will respect existing config overrides when updating an Entity.

Delete a Module

To delete a Module, you can navigate to the Module page and select Delete module from the Actions dropdown.

This will remove the Module from the Software Catalog.