Creating a Component Using a Component Template

Component Template Description

The component template supports only the YAML format. The created template file must be compressed into a ZIP package. Example structure of the package directory:

Component/  
├── spec.yaml  
├── variables.yaml 
├── values.yaml 
├── component/  
│   ├── demo_component.yaml  
│   ├── demo_config.yaml  
│   ├── deployment.yaml  
│   ├── configmap.yaml  
│   ├── service.yaml  
└───└── ...(Other Kubernetes resource files)

Kubernetes resource files take effect only for container-deployed components.

• spec.yaml: configuration information file, including the model version and Kubernetes resource creation sequence. Example file content:

  # Model version number. Currently, only v1.0.0 is available.
  model_version: v1.0.0
  
  # Component list.
  component:
    component_dir: comp_demo/
  
  # Kubernetes resource object.
  k8s_resources:
  # Type: SYSTEM (default sequence) or CUSTOM.
    order_type: CUSTOM
  # Sequence of the CUSTOM type.
    custom_orders:
      - ConfigMap
      - Deployment
      - Service

• variables.yaml: supported variable declaration file. All variables are declared in this file, including the variable name, type, description, and default value. Variables of the following types are supported: common types (string, integer, double, and bool), complex types (list(<T>), map(<T>), object(<T>)), ServiceStage model types (config, whose value is the group name or configuration name; runtimestack, whose value is the technology stack ID), and environment resource types (cce, ecs, customServer, elb, rds, dcs, cse, nacos, gaussdb, and dms_rocketmq (you can select multiple values and separate them with commas (,)). Example file content:

  variable:
    namespace:
      type: string
      default: demo
      description: namespace
    dep_name:
      type: string
      default: demo-dep
      description: workload name
    svc_port:
      type: integer
      default: 8080
      description: service port number
    value:
      type: string
      default: World
      description: Hello interface response data
    cce_resource:
      type: cce
      description: CCE resource
    image:
      type: string
      description: workload image
    labels:
      type: list(object({key = string, value = string}))
      default: [{"key":"key1", "value":"value1"}]
      description: component label
    resources:
      type: object({requests = object({cpu = string, memory = string}), limits = object({cpu = string, memory = string})})
      default: {"limits": {"cpu":"100m", "memory":"256Mi"}}
      description: container resource application configuration
    map_variable:
      type: map(list(object({name = string, age = integer})))
      default: {"persons": [{"name":"tom", "age": 20}], "animals": [{"name": "jack", "age": 18}]}
      description: combined data of the map, list, and object types

• values.yaml: variable value description file. Example file content:

  dep_name: demo-dep
  svc_port: 8080
  comp_cpu_request: 0.5
  comp_config: test-group/test.yaml
  comp_elb: elb-id-xxx
  comp_namespace: cce-id-xxx/default

• component: component directory. The directory name can be customized and contains the following files:
  • demo_component.yaml: component file. Only one component file can exist. For details, see demo_component.yaml.
  • demo_config.yaml: configuration file. A maximum of six configuration files are allowed. For details, see config_demo.yaml.
  • cce_xxx.yaml: workload type limit in Kubernetes resources. A maximum of 50 Kubernetes resources are allowed. There is only one Deployment, StatefulSet, DaemonSet, Pod, Job and CronJob resources, and the corresponding component is generated.
• demo_component.yaml: component file, which is used to describe component names and resources. Example file content:

  kind: ServiceStageComponent
  spec:
    name: ${var.comp_name}
    description: description
    # Either the environment ID or name must be specified. Query by ID is preferred.
    environment_id: ${var.env_id}
    environment_name: ${var.env_name}
    # Either the application ID or name must be specified. Query by ID is preferred.
    application_id: ${var.app_id}
    application_name: ${var.app_name}
    # Version is optional. If it is not specified, the system automatically generates one.
    version: 2024.0914.14111
    # Query by runtime_stack_id is preferred. If the value is empty, query by runtime_stack is used. The default value of runtime_stack is Docker.
    runtime_stack_id: ${var.runtime_id}
    runtime_stack:
      name: "OpenJDK8"
      version: "1.3.8"
      type: "Java"
      deploy_mode: "virtualmachine"
  
    source:
      kind: package
      storage: obs
      url: "obs://obs-lxz/unit-provider-1.0-SNAPSHOT.jar"
      http_username: null
      http_password: null
      http_command: null
      http_headers:
        - key: key
          value: value
    jvm_opts: "-Xms256m"
  
    # TomcatOptsV3 model
    tomcat_opts:
      server_xml: |
        <?xml version="1.0" encoding="UTF-8"?>
        <Server port="-1" shutdown="SHUTDOWN">
        </Server>
  
    # TongWebOptsV3 model
    tongweb_opts:
      tongweb_xml: |
        <?xml version="1.0" encoding="UTF-8"?>
        <Server port="-1" shutdown="SHUTDOWN">
        </Server>
      external_vmoptions: "-Xms256m"
  
    # Environment variables
    envs:
      - name: key1
        value: value1
      - name: key2
        value: value2
  
    deploy_strategy:
      type: RollingRelease
      rolling_release:
        fail_strategy: STOP
        batches: 1
        termination_period_seconds: 30
  
    update_strategy:
      type: RollingUpdate
      termination_period_seconds: 30
      max_unavailable: 2
    refer_resources:
      - type: dcs
        parameters:
          password: test-xxx
        // refer_alias can be left empty and is automatically set to distributed_session,distributed_cache.
        refer_alias: distributed_session,distributed_cache 
      - type: rds
        parameters:
          connection_type: JNDI
          jndi_name:
          db_name: demo
          db_user: root
          password: test-xxx
      - id: ${env.resources.elb.elb001.id}
        type: elb
        parameters:
          // Configure cert for HTTPS access.
          cert:
            id: xxxx
      - type: rds
        id: ${var.rds_id}
      - type: cce
        id: ${var.cce_id}
    configs:
      # config_name: reference configuration. The naming rule is as follows: group name/configuration name. If there is only one container, container_name can be left blank. If there are multiple containers, set container_name based on the container name.
      - config_name: group/filename.yaml
        mount_path: /teast.yaml
        container_name: default
      - config_name: ${var.config}
        mount_path: /teast1.yaml
        container_name: default
    external_accesses:
      - protocol: http
        forward_port: 8080
        address: demo.com
    enable_sermant_injection: false
    enable_sermant_spring_register: false
    enable_sermant_dubbo_register: false
    enable_sermant_config: false

  Component resources can be referenced in the following modes:

  • Specify only the resource type. The system automatically binds resources of this type in the environment. An error is reported when more than one resource meets the conditions.
  • Specify the logical ID of a resource. For example, ${env.resources.elb.elb001.id} matches the load balancer whose logical ID is elb001 in the environment.
  • Specify the physical resource ID, for example, ${var.cce_id}. cce_id is a variable of the cce type and its value is the CCE cluster ID.
• config_demo.yaml: configuration file, which describes the component configuration. Example file content:

  kind: ServiceStageConfig
  spec:
    name: test-group/test.yaml
    description: desc
    sensitive: true
    content: |
      test: world
      hello: 12313

Prerequisites

• An application has been created because components can be created only under an application. For details, see Creating an Application.
• An environment has been created based on the component deployment mode and resources have been managed because components need to be deployed in an environment.
  • For the environment types supported by each mode, see Component Deployment Modes.
  • For details about how to create an environment and manage resources, see Environment Management.
• You have compressed the prepared component template files into a ZIP package and uploaded the package to the repository. For details, see Component Template Description.
  • Upload the template package to the SWR repository. For details, see Uploading a Software Package.

    If PKIToken is disabled, the SWR repository is not supported.

  • Select the corresponding template package from OBS. Upload the template package to the OBS bucket in advance. For details, see Streaming Upload (PUT).
  • If you need to use JFrog (example) as the repository for storing the component template package, you can use an HTTP/HTTPS custom file download address as the component template package download address. Upload the component template package to the custom file address in advance.

  If the software package fails to be uploaded, see What If a Software Package Fails to Be Uploaded?

Creating a Component Using a Component Template

1. Log in to ServiceStage.
2. Use any of the following methods to go to the Create Component page.
   • Choose Component Management > Create Component > Use Template.
   • On the Application Management page, select the application for which you want to create a component, and click More > Use Template in the Operation column.
   • On the Application Management page, click the application for which you want to create a component. On the displayed Overview page, click Create Component > Use Template.

3. In the Basic Information area, configure the component by referring to the following table. Parameters marked with an asterisk (*) are mandatory.

   Parameter	Description
   *Application	Application to which the component belongs.
   *Environment	Component deployment environment.

4. In the Set Template Package area, select the uploaded component template package based on the template package storage mode.
   • CodeArts release repository: Click Select Software Package, select the uploaded template package from the CodeArts release repository, and click OK.
   • OBS: Click Select Software Package, select the uploaded template package from the OBS bucket, and click OK.
   • SWR repository: Click Select Software Package, select the uploaded template package from the SWR repository, and click OK.
   • Custom file address: If you need to use JFrog (example) as the repository for storing the template package, perform the following operations to obtain the template package that has been uploaded to the custom file address:
     1. Enter the HTTP/HTTPS custom file download address where the software package is located. The custom file address must be the complete path of the component template package file, for example, https://172.16.0.1:8082/artifactory/template-component.zip.
     2. Determine whether to enable authentication.

        If authentication is disabled, any user can download the software package in the custom file address by default.

        Click to enable authentication. Only authenticated users can download the software package in the custom file address. Authentication mode can be User name and password authentication or User-defined Header Authentication. The authentication mode and the corresponding authentication parameters are determined by the authentication mode supported by the server where the custom file directory is located.

5. Click Next.
   • In the Preview Template Package area, you can view the details of the component template file.
   • In the Set Parameters area, you can view and modify the component parameters.

6. Click Create and Deploy.
   • During component deployment, if the component configuration is incorrect, you can click Suspend to stop the deployment. Then, click Upgrade and reconfigure the component by referring to Upgrading a Component Using a Component Template.
   • On the View Deployment History page, view the deployment logs and wait until the component deployment is complete.

Follow-up Operations

• After a component created using a component template is deployed, the component can be upgraded only using the template. For details, see Upgrading a Component Using a Component Template.
• After a component created using a component template is deployed, maintain the component by referring to Component O&M.