Skip to main content

Custom Components

Custom components allow organizations to extend the capabilities of Klarity ImageFactory by adding their own scripts, configurations, and software installations. These components are private to the customer and provide a way to implement specific business requirements that are not covered by the standard system components.

Creating a Custom Component​

When creating a custom component, several key attributes must be defined to ensure it functions correctly within the ImageFactory pipeline:

  • Name: A descriptive name for the component (3 to 120 characters).
  • Description: An optional summary of what the component does (3 to 255 characters).
  • Stage: The execution phase, either BUILD (during image creation) or TEST (after build for validation).
  • Providers: A list of cloud providers where this component is supported (e.g., AWS, AZURE, GCP, VMWARE).
  • OS Types: The operating system families supported by the component (LINUX and/or WINDOWS).
  • Script Content: The actual code or playbook that will be executed.

Script Provisioners​

ImageFactory supports different provisioners for custom components, depending on the target operating system and the complexity of the task:

  1. SHELL: Used for standard Bash scripts on Linux.
  2. POWERSHELL: Used for PowerShell scripts on Windows.
  3. ANSIBLE: Used for Ansible playbooks on both Linux and Windows.

Important Restriction: Components assigned to the TEST stage cannot use the Ansible provisioner. Test stage components must be either SHELL or POWERSHELL scripts.

Script vs. Ansible Tags​

When defining a custom component with the Ansible provisioner, you have two options for providing the content:

  • Raw Script: You can provide the full content of the Ansible playbook as a string.
  • Ansible Tags: You can provide a list of references to existing Ansible roles or tags.

Note that you can provide either a raw script OR ansible_tags, but not both in the same component definition.

Version Management​

Every time you update the content of a custom component, ImageFactory automatically creates a new version. These versions are named using a timestamp format: YYYY-MM-DD_HH_MM_SS.

Key characteristics of component versions:

  • Immutability: Once a version is created, its content cannot be changed. This ensures that image builds are reproducible.
  • Latest Pointer: The most recently created version is automatically marked as the "latest" version.
  • Pinning: When referencing a component in an image template, you can either use the string latest to always use the newest version or pin to a specific timestamped version string.

Managing Custom Components​

To view, create, or edit custom components, navigate to Components in the sidebar. The interface allows you to browse all available components, create new ones, upload new script versions, and manage component metadata.

For a detailed walkthrough, see the Components guide.

Via API

Custom components can also be managed through the ImageFactory GraphQL API. Below are examples of common operations.

Creating a New Component​

mutation CreateCustomComponent($input: CreateComponentInput!) {
  createCustomComponent(input: $input) {
    id
    name
    stage
    provisioner
  }
}

Variables Example:

{
  "input": {
    "name": "Install Internal Tool",
    "description": "Installs the proprietary internal monitoring tool.",
    "stage": "BUILD",
    "provisioner": "SHELL",
    "os_types": ["LINUX"],
    "providers": ["AWS", "AZURE"],
    "script": "#!/bin/bash\ncurl -s http://repo.internal/install.sh | bash"
  }
}

Adding a New Version​

To update an existing component, you add a new version of its content:

mutation AddComponentVersion($componentId: ID!, $script: String!) {
  addComponentVersion(componentId: $componentId, script: $script) {
    version
    created_at
  }
}

Best Practices for Custom Components​

  • Idempotency: Ensure your scripts can be run multiple times without causing errors or inconsistent states. This is especially important for BUILD stage components.
  • Error Handling: Include proper error checking in your scripts. If a script exits with a non-zero status, ImageFactory will fail the build, preventing the creation of a broken image.
  • Logging: Print meaningful progress messages to standard output. These logs are captured by ImageFactory and are invaluable for debugging failed builds.
  • Security: Avoid hardcoding secrets or credentials in your component scripts. Use environment variables or secure secret management solutions provided by the cloud platform.