Components

Components are the building blocks of customization in Klarity ImageFactory. They consist of scripts or Ansible playbooks that execute during the image creation process to install software, apply security configurations, or verify the final artifact.

By using components, you can ensure that every image produced by ImageFactory meets your organization's specific requirements for security, performance, and functionality.

Component Types

ImageFactory categorizes components into two main types based on their ownership and availability.

• SYSTEM Components: These are predefined components managed by ImageFactory administrators. They're available to all customers and typically cover common tasks such as CIS hardening, installing monitoring agents, or applying standard OS patches.
• CUSTOM Components: These are created and managed by individual customers. They allow organizations to include their own proprietary scripts, internal tools, and specific configurations that aren't part of the standard system library.

Component Stages

Components are designed to run at specific points in the image lifecycle.

• BUILD Stage: These components execute while the temporary virtual machine is being configured. They make permanent changes to the operating system and file system before the final image is captured.
• TEST Stage: These components run after the image has been captured. ImageFactory launches a new instance from the captured image and executes the test scripts to verify that the build was successful and that all configurations are correct.

Script Provisioners

ImageFactory supports multiple provisioners to accommodate different scripting preferences and requirements.

Provisioner	Description
SHELL	Standard shell scripts for Linux distributions (e.g., Bash).
POWERSHELL	PowerShell scripts for Windows environments.
ANSIBLE	Ansible playbooks for complex configuration management. Note that Ansible is only supported for the BUILD stage.

Component Properties

A component definition includes several attributes that control where and how it can be used.

• Name and Description: Identifiers and documentation for the component.
• Providers List: The cloud providers (e.g., AWS, Azure) that the component supports.
• OS Types List: The operating systems (e.g., LINUX, WINDOWS) the component is compatible with.
• Unsupported Distributions: A list of specific OS versions or flavors where the component shouldn't be used.
• Stage: The execution stage (BUILD or TEST).
• Content: The actual script or playbook, which's versioned.

Version Management

Components support versioning to allow for safe updates and rollbacks. Each version is identified by a timestamp-based string.

• Latest Flag: One version of a component can be marked as "latest". Templates that use the latest keyword will automatically use this version.
• Script or Ansible Tags: The actual code or the specific tags to execute within an Ansible playbook.
• Script URL: An optional link to an external script file.
• Docs URL: A link to documentation explaining what the component does and how to use it.

Users can add new versions to a component as their requirements evolve. Older versions can be retained for compatibility with existing templates or removed if they're no longer needed.

Validation Rules

To prevent build failures and ensure consistency, ImageFactory enforces several validation rules when adding components to a template.

1. OS Compatibility: The component's supported OS types must match the template's distribution. You can't add a PowerShell component to a Linux template.
2. Provider Compatibility: The component must support the cloud provider defined in the template.
3. Stage Matching: A component must be used in the context of its defined stage. You can't use a TEST stage component in the build phase.
4. Ansible Restrictions: Ansible playbooks can't be used for TEST stage components. Additionally, Ansible playbooks must contain valid YAML and the hosts field must be set to either default or all.

Best Practices for Component Design

When creating custom components, consider the following guidelines to ensure they're reliable and maintainable.

• Idempotency: Scripts should be designed so they can run multiple times without causing errors or unexpected changes. This is especially important for Ansible playbooks.
• Error Handling: Include proper error checking and logging within your scripts. If a component fails, it should return a non-zero exit code so ImageFactory can flag the build as an error.
• Parameterization: Use component properties to make your scripts flexible. This allows you to use the same component in different templates with different settings.
• Documentation: Provide clear descriptions and documentation URLs for your components so other users understand their purpose and any required properties.

By following these principles, you can build a reliable library of components that simplify and automate your organization's golden image creation process.