Alauda DevOps Connectors Docs
  • English

    • ResourceInterface

    TOC

    OverviewProblem It SolvesData StructureHuman-Readable informationResource CategoriesParametersAttributesExpression SyntaxDependenciesWorkspacesConnectorClassDynamic FormOverviewExtended Context VariablesDynamic Form Configuration ApproachesDirect API ConfigurationReference OpenAPI Display SchemaExamplesWhat's NextReferences

    Overview

    ResourceInterface is a cluster-level resource that defines standardized abstractions for external resources (like Git repositories, OCI artifacts, Maven artifacts) and how they integrate into pipeline workflows. It serves as a bridge between connectors and pipeline orchestration, enabling seamless resource integration with minimal manual configuration.

    The following example defines a GitCodeRepository interface that describes Git repository access:

    apiVersion: connectors.alauda.io/v1alpha1
kind: ResourceInterface
metadata:
  name: gitcoderepository
  labels:
    resourceinterface.connectors.cpaas.io/category: "GitCodeRepository"
spec:
  params:
  - name: repository
    type: string
    description: "Repository name"
  - name: revision
    type: string
    default: "refs/heads/main"
    description: "Git revision (branch, tag, or commit)"
  attributes:
  - name: url
    type: string
    expression: "{connector.spec.address + '/' + params.repository}"
    parameterize:
      name: git-url
    dependsOn:
    - params.repository
    - connector
  workspaces:
  - name: git-basic-auth
    workspaceMapping:
      name: git-basic-auth
    value:
      csi:
        driver: connectors-csi
        readOnly: true
        volumeAttributes:
          connector.name: "{connector.metadata.name}"
          connector.namespace: "{connector.metadata.namespace}"
          configuration.names: "gitconfig"
          token.expiration: 30m

    ResourceInterface defines the following key aspects for resource integration:

    • Input parameters required for resource configuration
    • Output attributes calculated from parameters and connector information
    • Workspace definitions for volumes and credentials

    This document provides ResourceInterface Data Structure definition and Examples to help readers understand how to customize ResourceInterface.

    You don't need to understand the details of ResourceInterface unless you want to customize ResourceInterface.

    Problem It Solves

    When building CI/CD pipelines, users traditionally face several challenges:

    Manual Resource Entry: Users cannot easily browse and add external resources like Git repositories, OCI repositories, and other external services. They must manually enter URLs and set up workspaces, which is error-prone and time-consuming.

    Repetitive Execution Configuration: Every time users run a pipeline, they must manually enter version details like Git revision and target OCI tag, and repeatedly configure workspaces.

    Split Attributes: Attributes from the same remote resource are often split into different parameters. For example, the git-clone task requires separate url and revision parameters, plus workspace configurations for credentials and source code.

    Complex Workspace Selection: The pipeline workspace selection process lists all available options but provides little guidance on which connector type is appropriate for each workspace.

    ResourceInterface addresses these issues by providing a standardized way to describe and integrate external resources into pipeline workflows, enabling users to browse and select resources through UI interfaces while automatically generating the correct configuration and credentials.

    Data Structure

    ResourceInterface is a cluster-level k8s resource

    • Kind: ResourceInterface
    • API Version: connectors.alauda.io/v1alpha1

    Human-Readable information

    ResourceInterface is a standard k8s resource, it can be annotated with human-readable information using annotations.

    KeyPositionDescription
    cpaas.io/display-nameannotationsDisplay name for ResourceInterface, optional.
    cpaas.io/descriptionannotationsDescription for ResourceInterface, optional.
    apiVersion: connectors.alauda.io/v1alpha1
kind: ResourceInterface
metadata:
  name: gitcoderepository
  annotations:
    cpaas.io/display-name: "Git Code Repository"
    cpaas.io/description: "GitCodeRepository is a resource interface for Git code repository"

    you can also use style.tekton.dev/descriptors annotation to describe the params for dynamic form.

    metadata:
  annotations:
    style.tekton.dev/descriptors: |-
      - path: params.revision
        x-descriptors:
          - urn:alm:descriptor:widgets:select
          - urn:alm:descriptor:expression:props.options:schema:openapi:context.connectorClass.spec.api.openapi:listGitRefs

    more details please refer to dynamic-form.

    Resource Categories

    ResourceInterface organizes resources into categories that define common contracts and behaviors. Categories are marked using the label resourceinterface.connectors.cpaas.io/category.

    metadata:
  labels:
    resourceinterface.connectors.cpaas.io/category: "GitCodeRepository"

    Multiple ResourceInterfaces can belong to the same category (e.g., gitcoderepository and githubcoderepository both belong to the GitCodeRepository category). Resources in the same category must provide the same standard attributes and workspaces to ensure compatibility.

    Parameters

    Parameters define the input data required to configure the resource when integrated into a pipeline. These parameters influence the calculation of output attributes.

    Parameters are defined in spec.params and follow Tekton parameter types:

    • name: Parameter name
    • type: Supports string, array, object (consistent with Tekton ParamSpec types)
    • default: Default parameter value (optional)
    • description: Parameter description for UI display (optional)

    for example:

    kind: ResourceInterface
metadata:
  name: gitcoderepository
  labels:
    resourceinterface.connectors.cpaas.io/category: "GitCodeRepository"
spec:
  params:
  - name: repository
    type: string
    description: "Repository name"
  - name: revision
    type: string
    default: "refs/heads/main"
    description: "Git revision (branch, tag, or commit)"

    Attributes

    Attributes define the output values calculated from input parameters and connector information. They can be consumed by pipeline tasks as parameters and may be elevated to pipeline-level parameters.

    Attributes are defined in spec.attributes:

    • name: Attribute name
    • type: Value type - supports string, array
    • expression: JavaScript expression for calculating the attribute value
    • parameterize: Parameterization configuration
      • name: Default parameter name when parameterized
      • disable: Whether to disable parameterization
    • dependsOn: Dependencies on parameters or connector

    for example:

    spec:
  attributes:
  - name: url
    type: string
    expression: "{connector.spec.address + '/' + params.repository}"
    parameterize:
      name: git-url
    dependsOn:
    - params.repository
    - connector
  - name: artifact-versions
    type: array
    expression: "{params.tags.map(tag => connector.spec.registry + '/' + params.repository + ':' + tag)}"
    dependsOn:
    - params.repository
    - params.tags
    - connector

    Expression Syntax

    Expressions use JavaScript syntax and support:

    • String concatenation: params.organization + '/' + params.repository
    • Object property access: connector.metadata.name
    • Array operations: params.tags.map(tag => connector.spec.address + ':' + tag)
    • Built-in functions:
      • url(connector.spec.address).host: get the host of the address

    and other JavaScript syntaxes are supported.

    Available Context:

    • connector: Current connector information, the structure of connector please refer to Concept of Connector
    • params: Current parameter values

    the context data structure is:

    {
  "params": {
    "param-name1": "param-value",
    "param-name2": "param-value"
  },
  "connector": {}
}

    Security: Frontend executes JavaScript code in a sandbox environment, allowing only safe, sandboxed functions.

    Example:

    • {connector.spec.address + '/' + params.repository}: get the address of the repository
    • {url(connector.spec.address).host + '/' + params.repository + ':' + params.tag}: get the address of the artifact
    • {params.tags.map(tag => url(connector.spec.address).host + '/' + params.repository + ':' + tag)}: get the addresses of the artifacts array by iterating the tags array

    Dependencies

    Dependencies specify what parameters or connector information an attribute calculation depends on:

    • params.<param-name>: Depends on a specific parameter value
    • connector: Depends on connector selection

    Workspaces

    Workspaces define volumes and credentials provided by the resource interface. They enable automatic provisioning of required resources for pipeline tasks.

    Workspaces are defined in spec.workspaces:

    • name: Workspace name
    • workspaceMapping.name: Default workspace name when added to pipeline workspaces
    • value: Default workspace value (follows Tekton WorkspaceBinding format), consistent with Tekton WorkspaceBinding types

    for example:

    spec:
  workspaces:
  - name: git-source
    workspaceMapping:
      name: git-source
    value:
      volumeClaimTemplate:
        spec:
          accessModes: [ReadWriteMany]
          resources:
            requests:
              storage: 1Gi
  - name: git-basic-auth
    workspaceMapping:
      name: git-basic-auth
    value:
      csi:
        driver: connectors-csi
        readOnly: true
        volumeAttributes:
          connector.name: "{connector.metadata.name}"
          connector.namespace: "{connector.metadata.namespace}"
          configuration.names: "gitconfig"
          token.expiration: 30m

    Workspace values support expressions to dynamically reference parameter and connector values using the same syntax as attributes.

    ConnectorClass

    ConnectorClasses mark supported ResourceInterfaces through labels resourceinterface.connectors.cpaas.io/<resource-interface-name>: "true", for example:

    metadata:
  labels:
    resourceinterface.connectors.cpaas.io/gitcoderepository: "true"
    resourceinterface.connectors.cpaas.io/githubcoderepository: "true"

    This enables the system to match compatible connectors with ResourceInterfaces and provide appropriate parameter forms based on ResourceInterface definitions.

    More about ConnectorClass please refer to Concept of ConnectorClass

    Dynamic Form

    Dynamic forms provide a declarative way to configure interactive UI components for Pipeline Integration. With dynamic forms, users can browse and select resources such as Git repositories and revisions directly through the connector.

    Overview

    Use the style.tekton.dev/descriptors annotation to define dynamic form behavior for parameters. Here is an example:

    metadata:
  annotations:
    style.tekton.dev/descriptors: >-
      - path: params.repository
        x-descriptors:
          - urn:alm:descriptor:com.tectonic.ui:select:repository
          - urn:alm:descriptor:expression:props.options:api:/clusters-rewrite/${context.cluster}${context.connector.status.api.path}/api/v4/projects?simple=true
          - urn:alm:descriptor:expression:props.options:label:path:path_with_namespace
          - urn:alm:descriptor:expression:props.options:value:path:path_with_namespace
          - urn:alm:descriptor:label:en:Repository
          - urn:alm:descriptor:label:zh:Repository
          - urn:alm:descriptor:description:zh:Repository path including group name or username, e.g. mygroup/my-app.
          - urn:alm:descriptor:description:en:Repository path including group name or username, e.g. mygroup/my-app.

    The syntax follows the Pipeline Dynamic Forms specification. Familiarity with that documentation is recommended before proceeding.

    In addition to the standard capabilities, dynamic forms in ResourceInterface support:

    • Extended context variables for accessing connector and ResourceInterface data
    • Reference OpenAPI display schema definitions in ConnectorClass for centralized API configuration and reference the api definition when using dynamic form

    Extended Context Variables

    The following context variables are available in ResourceInterface dynamic forms:

    VariableDescription
    context.connectorThe Connector object. Access any field, e.g., context.connector.status.api.path
    context.connectorClassThe ConnectorClass object. Access any field, e.g., context.connectorClass.spec.api.openapi
    context.paramsParameter values in Pipeline Integration UI form, e.g., context.params.repository
    context.resourceInterfaceThe ResourceInterface object. Access any field as needed

    Dynamic Form Configuration Approaches

    There are two approaches to configure dynamic forms in ResourceInterface:

    1. Direct API Configuration: Call connector APIs directly using descriptor expressions. This approach is straightforward and easy to understand. The Connectors System provides Connector API endpoints for listing repositories, git references, and more.

    2. Reference OpenAPI Display Schema in ConnectorClass: Define API calls and display mappings in the ConnectorClass using spec.api.openapi. This approach centralizes API definitions and display configurations, avoiding duplication across multiple ResourceInterfaces. When using dynamic form, you can reference the API definition in the ConnectorClass directly.

    You can use either approach independently or combine them as needed.

    Direct API Configuration

    Example: Listing GitLab Repositories

    GitLab connectors expose the native GitLab API, which can be used to populate a repository selector:

    kind: ResourceInterface
metadata:
  name: gitlabcoderepository
  annotations:
    style.tekton.dev/descriptors: >-
      - path: params.repository
        x-descriptors:
          - urn:alm:descriptor:com.tectonic.ui:select:repository
          - urn:alm:descriptor:expression:props.options:api:/clusters-rewrite/${context.cluster}${context.connector.status.api.path}/api/v4/projects?simple=true
          - urn:alm:descriptor:expression:props.options:label:path:path_with_namespace
          - urn:alm:descriptor:expression:props.options:value:path:path_with_namespace
          - urn:alm:descriptor:label:en:Repository
          - urn:alm:descriptor:label:zh:Repository
          - urn:alm:descriptor:description:zh:Repository path including group name or username, e.g. mygroup/my-app.
          - urn:alm:descriptor:description:en:Repository path including group name or username, e.g. mygroup/my-app.

    Example: Listing Git References

    Git connector provides a gitrefs endpoint for listing branches and tags:

    kind: ResourceInterface
metadata:
  name: gitcoderepository
  annotations:
    style.tekton.dev/descriptors: >-
      - path: params.revision
        x-descriptors:
          - urn:alm:descriptor:com.tectonic.ui:select:revision
          - urn:alm:descriptor:expression:props.options:api:/clusters-rewrite/${context.cluster}${context.connector.status.api.path}/git/gitrefs?repositoryUrl=${context.connector.spec.address + "/" + context.params.repository + ".git"}&search=${current.search}
          - urn:alm:descriptor:expression:props.options:path:items
          - urn:alm:descriptor:expression:props.options:label:path:name
          - urn:alm:descriptor:expression:props.options:value:path:name
          - urn:alm:descriptor:label:en:Revision
          - urn:alm:descriptor:label:zh:Revision
          - urn:alm:descriptor:description:zh:Git revision reference, e.g. refs/heads/main.
          - urn:alm:descriptor:description:en:Git revision reference (e.g., refs/heads/main for branches)

    Reference OpenAPI Display Schema

    To centralize API definitions and display configurations, define them in the ConnectorClass using spec.api.openapi. Dynamic forms can then reference these definitions directly, eliminating redundant configurations across ResourceInterfaces.

    Prerequisites

    1. Define the OpenAPI specification in the ConnectorClass. See ConnectorClass OpenAPI Description for details.
    2. Add the x-display-schema extension to define how the API integrates with dynamic forms.

    Display Schema Structure

    The x-display-schema extension contains:

    • parameters[]: Defines how to populate API parameters at runtime.
      • name: Parameter name (must match the API parameter name)
      • value: Parameter value expression. Syntax follows Pipeline Dynamic Forms.
    • descriptors: Defines how API response data maps to form options. Syntax follows Pipeline Dynamic Forms.

    Example: Git References API

    The following ConnectorClass configuration defines the GET /git/gitrefs API with display schema:

    • The repositoryUrl parameter is set to ${context.connector.spec.address + "/" + context.params.repository + ".git"} and passed as a query parameter
    • The search parameter is set to ${current.search} for filtering results
    • The response items array is mapped to select options, using name for both label and value

    example:

    kind: ConnectorClass
spec:
  api:
    openapi:
      openapi: 3.0.3
      info:
        title: Git API
        version: v1alpha1
      paths:
        /git/gitrefs:
          get:
            x-provider-type: api
            x-display-schema:
              parameters:
              - name: repositoryUrl
                value: ${context.connector.spec.address + "/" + context.params.repository + ".git"}
              - name: search
                value: ${current.search}
              descriptors:
              - urn:alm:descriptor:expression:props.options:path:items
              - urn:alm:descriptor:expression:props.options:label:path:name
              - urn:alm:descriptor:expression:props.options:value:path:name
            operationId: listGitRefs
            parameters:
            - name: repositoryUrl
              in: query
              description: "Cloneable URL of the repository (e.g., https://github.com/mygroup/my-app.git)"
              required: true
              schema:
                type: string
            - name: search
              in: query
              description: "Return list of git references containing the search string"
              required: false
              schema:
                type: string
            responses:
              '200':
                description: "All git references for a repository"
                content:
                  application/json: {}

    Referencing OpenAPI in ResourceInterface

    Once the API is defined in ConnectorClass, reference it in your ResourceInterface using the following syntax:

    • urn:alm:descriptor:widgets:select to specify the widget type
    • schema:openapi:context.connectorClass.spec.api.openapi:<operationId> to reference the API definition in the ConnectorClass

    for example:

    kind: ResourceInterface
metadata:
  name: gitcoderepository
  annotations:
    style.tekton.dev/descriptors: >-
      - path: params.revision
        x-descriptors:
          - urn:alm:descriptor:widgets:select
          - urn:alm:descriptor:expression:props.options:schema:openapi:context.connectorClass.spec.api.openapi:listGitRefs
          - urn:alm:descriptor:label:en:Revision
          - urn:alm:descriptor:label:zh:Revision
          - urn:alm:descriptor:description:zh:Git revision reference, e.g. refs/heads/main.
          - urn:alm:descriptor:description:en:Git revision reference (e.g., refs/heads/main for branches)

    With this configuration, the revision field in Pipeline Integration renders as a dropdown that fetches options from the listGitRefs API.

    Examples

    GitCodeRepository ResourceInterface

    apiVersion: connectors.alauda.io/v1alpha1
kind: ResourceInterface
metadata:
  name: gitcoderepository
  labels:
    resourceinterface.connectors.cpaas.io/category: "GitCodeRepository"
spec:
  params:
  - name: repository
    type: string
    description: "Repository name"
  - name: revision
    type: string
    default: "refs/heads/main"
    description: "Git revision"
  attributes:
  - name: url
    type: string
    expression: "{connector.spec.address + '/' + params.repository}"
    parameterize:
      name: git-url
    dependsOn:
    - params.repository
    - connector
  - name: revision
    type: string
    expression: "{params.revision}"
    parameterize:
      name: git-revision
    dependsOn:
    - params.revision
  workspaces:
  - name: git-source
    workspaceMapping:
      name: git-source
    value:
      volumeClaimTemplate:
        spec:
          accessModes: [ReadWriteMany]
          resources:
            requests:
              storage: 200Mi
  - name: git-basic-auth
    workspaceMapping:
      name: git-basic-auth
    value:
      csi:
        driver: connectors-csi
        readOnly: true
        volumeAttributes:
          connector.name: "{connector.metadata.name}"
          connector.namespace: "{connector.metadata.namespace}"
          configuration.names: "gitconfig"
          token.expiration: 30m

    OCIArtifact ResourceInterface

    apiVersion: connectors.alauda.io/v1alpha1
kind: ResourceInterface
metadata:
  name: ociartifact
  labels:
    resourceinterface.connectors.cpaas.io/category: "OCIArtifact"
spec:
  params:
  - name: repository
    type: string
    description: "Repository name"
  - name: tags
    type: array
    description: "Image tags"
  attributes:
  - name: repository-address
    type: string
    expression: "{connector.spec.registry + '/' + params.repository}"
    dependsOn:
    - params.repository
    - connector
  - name: artifact-versions
    type: array
    expression: "{params.tags.map(tag => connector.spec.registry + '/' + params.repository + ':' + tag)}"
    dependsOn:
    - params.repository
    - params.tags
    - connector
  workspaces:
  - name: docker-config
    workspaceMapping:
      name: docker-config
    value:
      csi:
        driver: connectors-csi
        readOnly: true
        volumeAttributes:
          connector.name: "{connector.metadata.name}"
          connector.namespace: "{connector.metadata.namespace}"
          configuration.names: "config"
          token.expiration: 60m

    What's Next

    • Understand Pipeline Integration When you want to integrate Connector in your custom Pipeline or Task.

    References