Custom Step Development Guide¶

YAML File Template¶

The declaration file is used to define information such as the custom step's name, version, and parameters. To align more closely with cloud-native practices, the plugin definitions in the Application Workbench follow the style of Kubernetes resources. Although they currently do not exist as CRDs, the plugin definition is as follows:

apiVersion: pipeline.amamba.io/v1alpha1
kind: PipelinePlugin
metadata:
  name: deploy-application      # required. Plugin ID; only lowercase letters, numbers, and delimiters ("- _") are allowed.
  labels:
    pipeline.amamba.io/category: build   # Must be one of: others, build, test, security, release, deploy, command, general, repository, quality.
    pipeline.amamba.io/hidden: false     # Whether the plugin is hidden.
    pipeline.amamba.io/version: 1.0.0    # required. Plugin version; must be unique in combination with name.
  annotations:
    pipeline.amamba.io/description: Deploy applications to the Kubernetes cluster   # Plugin description.
    pipeline.amamba.io/versionDescription: Fixed xxx issue  # Plugin version description.
    pipeline.amamba.io/icon: Plugin icon URL              # Icon URL.
spec:
  image: "docker.m.daocloud.io/amambadev/jenkins-agent-base:v0.3.2-podman"  # required. Base image for the plugin. Must be a public image with no login required.
  entrypoint: ""                    # Optional custom entry script, essentially replacing --entrypoint.
  shell: "/bin/bash"
  script: "kubectl apply -f ."      # required. The script to be executed in the container.
  params:                           # required
    - name: namespace               # required. Must be unique.
      sort: 2                       # Display order of the parameter.
      uiType: NamespaceSelector
      type: string
      uiConfig:
        displayName: "Namespace"
        placeholder: "namespace"
        tips: "Namespace where the application will be deployed."
        helper: "Namespace not found? Go to global management to configure."
      validate:
        required: true
        requiredMessage: "Namespace cannot be empty."
        pattern: ^[a-zA-Z0-9_-]+$
        patternMessage: "Namespace can only contain letters, numbers, underscores, and hyphens."
        minLength: 1
        maxLength: 64
        immutable: false               # Whether the parameter is editable.
        default: "my-namespace"        # Default value.
        options:
          - label: Default
            value: default
      env: NAMESPACE                  # If the 'env' field exists, the value will be used as the environment variable key; otherwise, it defaults to the parameter name.
      dependProperties:                # Property dependencies for frontend interaction. For example, the namespace field may depend on the cluster field.
        cluster: cluster
        namespace: namespace

Parameter Description¶

Attribute Name	Meaning	Example
name	Parameter name	cluster
type	Parameter type	Supported types: string, int, bool, float, array, map
env	Corresponding environment variable; defaults to `name` if not provided	CLUSTER_NAME
validate	Parameter validation rules	{}
uiConfig	UI display options	{}
dependProperties	Parameter dependencies for frontend usage	e.g., `namespace` depends on `cluster`; used for frontend interaction

Introduction to dependProperties¶

Some parameters have dependency relationships. For example, namespace depends on cluster. For a better UI interaction experience, you can define these dependencies in dependProperties. The frontend will dynamically fetch and display data based on uiType and dependProperties.

dependProperties is a map structure where the key is the parameter name used in the frontend component, and the value is the name of the parameter defined in params. Multiple dependencies can be declared.

Dependency Example¶

NamespaceSelector Example:

params:
  - name: cls                 
    uiType: ClusterSelector
  - name: namespace                 
    uiType: NamespaceSelector
    dependProperties:
      cluster: cls      # Key is used in the frontend; value refers to the parameter defined in params.

WorkloadSelector Example:

params:
  - name: cls                 
    uiType: ClusterSelector
  - name: namespace                 
    uiType: NamespaceSelector
    dependProperties:  
      cluster: cls
  - name: workloadType
    uiType: Select
  - name: workloadName                 
    uiType: WorkloadSelector    # Cascading dependencies on cluster, namespace, and workloadType.
    dependProperties:  
      cluster: cls
      namespace: namespace   
      workloadType: workloadType

ContainerSelector Example:

params:
  - name: cls                 
    uiType: ClusterSelector
  - name: namespace                 
    uiType: NamespaceSelector
    dependProperties:  
      cluster: cls
  - name: workload_type
    uiType: Select
  - name: workloadName                 
    uiType: WorkloadSelector
    dependProperties:  
      cluster: cls
      namespace: namespace   
      workloadType: workload_type 
  - name: containerName
    uiType: ContainerSelector
    dependProperties:
      cluster: cls
      namespace: namespace
      workloadType: workload_type
      workloadName: workloadName

validate (Parameter Validation Rules)¶

required:  true                 # Required field or not.
requiredMessage: 'Required'      # Prompt when the field is required but not filled in.
pattern: '*'                    # Valid regular expression pattern.
patternMessage: 'Not matched'    # Prompt when the regex doesn't match.
min: 0                          # Minimum value (valid number).
max: 1                          # Maximum value (must be > min).
minLength: 64                   # Minimum length.
maxLength: 64                   # Maximum length.
integer: true                   # Whether the value must be an integer.
immutable: false                # Whether the field is editable (false = editable, true = read-only).
default: 'cluster1'             # Default value.
options:
  - label: 'Cluster 1'          # For dropdown selectors.
    value: 'cluster1'

uiConfig Parameter Description¶

uiConfig must be a predefined type and is primarily used for display configurations on the UI:

displayName: Display name
helper: Help information (displayed below the input box)
tips: Tooltip (appears when hovering or clicking the “?”)
placeholder: Placeholder text

Predefined UI types and their usage scenarios:

UI Type	Parameter Type	Description	Dependencies
Text	string	Large text input field
Shell	string	Shell syntax-highlighted input box
Yaml	string	YAML syntax-highlighted input box
Input	string	Single-line input field
Select	string	Dropdown selector (used with `options`)
Radio	string	Radio button
Switch	bool	Switch toggle
Password	string	Password field (`****`)
Number	int	Numeric input field
ImageInput	string	Image selector
ClusterSelector	string	Cluster selector
NamespaceSelector	string	Namespace selector	Depends on the `cluster` parameter.
CredentialSelector	string	Credential selector
WorkloadSelector	string	Workload selector	Depends on `cluster`, `namespace`, and `workloadType` parameters.
ContainerSelector	string	Container selector	Depends on `cluster`, `namespace`, `workloadType`, and `workloadName`.
Strings	array	Array of strings
Numbers	array	Array of numbers
KV	map	Key-value pair structure (e.g., environment variables)
Ignore	bool	Field will not be displayed
CPUNumber	float	CPU quantity input box
MemoryNumber	float	Memory quantity input box