Creating a product for Managed Service for Kubernetes

To add a software product for Managed Service for Kubernetes in Marketplace, upload its packages to the Yandex Cloud registry. This section will help you prepare your Marketplace product for Yandex Managed Service for Kubernetes.

For more information about setting up subscription-based product access, see Integration with the License Manager API.

You can also create products for Yandex Compute Cloud to run on Linux by following the relevant guidelines.

Hosting and naming imagesHosting and naming images

• The product’s Helm chart and all Docker images it includes must reside in the publisher registry created in Yandex Container Registry. To learn how to create a registry and push an image, see the relevant guides.

• The product’s Helm chart name must follow this format:

  cr.yandex/<registry-id>/<vendor-name>/<product-name>/<chart>
  

  Where:

  • <registry-id>: Publisher's registry ID.
  • <vendor-name>: Names of the product publisher.
  • <product-name>: Product names.
  • <chart>: Helm chart name.

• The product’s Docker image names must follow this format:

  cr.yandex/<registry-id>/<vendor-name>/<product-name>/<component-name>:<tag>
  

  Where:

  • <registry-id>: Publisher's registry ID.
  • <vendor-name>: Names of the product publisher.
  • <product-name>: Product names.
  • <component-name>: Name of the product component provided as a Docker image.
  • <tag>: Docker image tag. Do not use the latest tag.

By default, during publication, all the images that come with the product are moved from the publisher's registry to the public yc-marketplace registry. The whole product hierarchy defined by the publisher is maintained in the process. To avoid moving images to the yc-marketplace registry, use the private_artifacts parameter in the product specification.

For example, the cr.yandex/b1gq90dgh25bebiu75o/yandex-cloud/prometheus/pushgateway:1.0 image will be published as cr.yandex/yc-marketplace/yandex-cloud/prometheus/pushgateway:1.0.

For more information on using the registry, see Pushing a Helm chart to a registry and Pushing a Docker image to a registry.

Helm chart build featuresHelm chart build features

A Helm chart must contain a file named values.yaml listing all Docker images as parameters. The names of Docker images in values.yaml must start with the .Values prefix and refer to images in the publisher registry to ensure error-free publication and subsequent installation of the product in the user’s cluster.

Generic pod specification without parameters:

# pod spec
spec:
  containers:
  - image: cr.yandex/<registry-id>/<vendor-name>/<product-name>/<component-name>:<tag>

Pod specification with image name replaced with the YAML path variable described in values.yaml:

# pod spec
spec:
  containers:
  - image: {{ .Values.images.pushgateway }}

# values.yaml
images:
  pushgateway: cr.yandex/<registry-id>/<vendor-name>/<product-name>/<component-name>:<tag>

Product specificationProduct specification

To publish a product, you need a specification describing the product’s deployment parameters. Create your product’s specification and upload it to Yandex Object Storage.

The product specification uses YAML format and contains the following data:

1. name: Default name of the app when deployed to the user’s cluster.

   name: "our-app"
   

2. helm_charts: Required field. It contains a list of the product’s Helm chart names and tags. You can specify only one Helm chart.

   helm_charts:
     - name: cr.yandex/b1gq90dgh25bebiu75o/Vendor/Product/chart
       tag: 1.0-0
       images:
         - registry: app1.image.registry
           name_without_registry: app1.image.name
           tag: app1.image.tag
         - name_with_registry: app2.config.image.name
           tag: app2.config.image.tag
         - full: another-whatever-key.subkey.name
       # This indicates that all specified values apply to this chart.
       reuse_values: true
   

   The Helm chart must have the images field specified. It contains a list of metadata of the images included in the product. The values of image metadata variables are YAML Path format references to variables from values.yaml. Entries can be in one of the following formats:

   • Image name, registry address, and tag are described in separate fields:

     images:
     - registry: images.app.image.registry
       name_without_registry: images.app.image.name
       tag: images.app.image.tag
     

     # values.yaml
     images:
       app:
         image:
           registry: "cr.yandex"
           name: "<registry-id>/<vendor-name>/<product-name>/<component-name>"
           tag: "<tag>"
     

   • Image name and registry address are described in one field, the tag in a different field:

     images:
       - name_with_registry: images.app.config.image.name
         tag: images.app.config.image.tag
     

     # values.yaml
     images:
       app:
         config:
           image:
             name: "cr.yandex/<registry-id>/<vendor-name>/<product-name>/<component-name>"
             tag: "<tag>"
     

   • The full path to the image is provided:

     images:
       - full: images.app.image.name
     

     # values.yaml
     images:
       app:
         image:
           name: "cr.yandex/<registry-id>/<vendor-name>/<product-name>/<component-name>:<tag>"
     

3. requirements: Required field. Required parameters of the cluster where the product will be deployed. This section must include the min_k8s_version parameter that defines the range of supported Kubernetes versions.

   requirements:
     min_k8s_version: ">=1.18"
   

4. user_values: Optional parameter. It stands for a list of product variables the user can override while installing or modifying an already installed product via the Yandex Cloud management console. Each variable is described by the required fields below:

   • name: YAML Path of the variable from values.yaml.

   • title: Short name of the variable, either in Russian or English. The value must start with a capital letter.

     user_values:
     - name: app.port
       title:
         en: <english_title>
         ru: <russian_title>
     

   • description: Variable description, either in Russian or English. The value must start with a capital letter.

     user_values:
       - name: app.port
         title: <Title>
         description:
           en: <English_description>
           ru: <Russian_description>
     

   • required (optional): Required flag. The flag can be set for any variable type except boolean_value. The available values are true and false.

   • Variable type. Legal values:

     • simple_disabled. May contain a default value and the enable flag.

       user_values:
         - name: <name>
           disabled: true
           title: <Title>
           simple_disabled:
             required: true
             default_value: "simple_string_value"
       

     • integer_value. May contain a default value and a range of valid values.

       user_values:
         - name: <name>
           title: <Title>
           description: <Description>
           integer_value:
             default_value: <default_integer>
             required: true
             restrictions:
               min: <integer_1>
               max: <integer_2>
       

     • boolean_value. May contain a default value.

       user_values:
         - name: <name>
           title: <Title>
           description: <Description>
           boolean_value:
             default_value: true
       

     • string_selector_value: String from a pre-defined list. May contain a default value and a list of valid values.

       user_values:
         - name: <name>
           title: <Title>
           description: <Description>
           string_selector_value:
             default_value: <value_1>
             required: true
             values:
               - <value_1>
               - <value_2>
               - <value_3>
       

     • integer_selector_value: Integer value from a pre-defined list. May contain a default value and a list of valid values.

       user_values:
         - name: <name>
           title: <Title>
           description: <Description>
           integer_selector_value:
             default_value: <integer_1>
             required: true
             values:
               - <integer_1>
               - <integer_2>
               - <integer_3>
       

     • string_value: May contain a flag and a secret field, as well as a value length limit.

       user_values:
         - name: <name>
           title: <Title>
           description: <Description>
           string_value:
             required: true
             secret: true
             length_restrictions:
               min: <minimum_string_length>
               max: <maximum_string_length>
       

     • list_value. It may contain fields available for the specified list item type. List items can be of any type supported in user_values; however, the list can only contain items of the same type.

       user_values:
         - name: <name>
           title: <Title>
           description: <Description>
           list_value:
             item:
              <list_item_type>: 
                required: true
             min_items: <minimum_number_of_list_items>
             max_items: <maximum_number_of_list_items>
       

     • cloudiddisabled: Cloud ID in Yandex Cloud. If you provide a parameter, the appropriate product field in the management console will not be available for editing and will be automatically pre-filled.

       user_values:
         - name: <name>
           title: <Title>
           cloud_id_value:
             required: true
       

     • cloudid: Cloud ID in Yandex Cloud which you can select from the management console.

       user_values:
         - name: <name>
           title: <Title>
           cloud_id_value:
             required: true
       

     • folderid: Folder ID.

       user_values:
         - name: <name>
           title: <Title>
           folder_id_value:
             required: true
       

     • clusterid: Kubernetes cluster ID.

       user_values:
         - name: <name>
           title: <Title>
           cluster_id_value:
             required: true
       

     • networkid: Yandex Virtual Private Cloud network ID.

       user_values:
         - name: <name>
           title: <Title>
           network_id_value:
             required: true
       

     • subnetid: Virtual Private Cloud subnet ID.

       user_values:
         - name: <name>
           title: <Title>
           subnet_id_value:
             required: true
       

     • serviceaccountid: Service account ID.

       user_values:
         - name: <name>
           title: <Title>
           service_account_id_value:
             required: true
       

     • serviceaccountkey: Service account's authorized key.

       user_values:
         - name: <name>
           title: <Title>
           service_account_key_value:
             required: true
       

     • service_account_aws_key_value: Service account's static key for access to Object Storage. It is delivered in JSON format.

       user_values:
         - name: <name>
           title: <Title>
           description: <Description>
           service_account_aws_key_value:
             required: true
       

       To use the value of this field in a Helm chart or provide it in a file during manual installation, add the following code at the end of the templates/_helpers.tpl template:

       Warning

       Make sure to put _generated after the name field value from the specification.

       {{- define "<chart_name>.access_key_id" -}}
       {{- if .Values.saAccessKeyFile -}}
       {{- $key := .Values.saAccessKeyFile | fromJson -}}
       {{- $key.access_key.key_id -}}
       {{- else }}
       {{- .Values.<name_field_value_from_specification>_generated.accessKeyID -}}
       {{- end }}
       {{- end }}
       
       {{- define "<chart_name>.access_key_secret" -}}
       {{- if .Values.saAccessKeyFile -}}
       {{- $key := .Values.saAccessKeyFile | fromJson -}}
       {{- $key.secret -}}
       {{- else }}
       {{- .Values.<name_field_value_from_specification>_generated.secretAccessKey -}}
       {{- end }}
       {{- end }}
       

       Example of using values in the Secret object template:

       apiVersion: v1
       kind: Secret
       metadata:
         name: {{ include "mychart.fullname" . }}
         labels:
           {{- include "mychart.labels" . | nindent 4 }}
       type: Opaque
       data:
         ACCESS_KEY_ID: {{ include "mychart.access_key_id" . | b64enc | quote }}
         SECRET_ACCESS_KEY: {{ include "mychart.access_key_secret" . | b64enc | quote }}
       

     • ciliumvaluedisabled: Use of the Cilium network policy provider. If you provide a parameter, the appropriate product field in the management console will not be available for editing and will be automatically pre-filled.

       user_values:
         - name: <name>
           title: <Title>
           cilium_value: {}
       

     • ciliumvalue: Use of the Cilium network policy provider.

       user_values:
         - name: <name>
           title: <Title>
           cilium_value: {}
       

     • kubednsclusteripvaluedisabled: IP address of the Kubernetes cluster. If you provide a parameter, the appropriate product field in the management console will not be available for editing and will be automatically pre-filled.

       user_values:
         - name: <name>
           title: <Title>
           kube_dns_cluster_ip_value:
             required: true
       

     • kubednsclusteripvalue: IP address of the Kubernetes cluster.

       user_values:
         - name: <name>
           title: <Title>
           kube_dns_cluster_ip_value:
             required: true
       

     • loggroupidvalue: Yandex Cloud Logging log group ID.

       user_values:
         - name: <name>
           title: <Title>
           log_group_id_value:
             required: true
       

     • kmskeyidvalue: Yandex Key Management Service key content.

       user_values:
         - name: <name>
           title: <Title>
           kms_key_id_value:
             required: true
       

     • domainvalue: Domain to host the Kubernetes cluster.

       user_values:
         - name: <name>
           title: <Title>
           domain_value:
             required: true
       

     • iamapikeyvalue: Service account's API key value. It is delivered in JSON format.

       user_values:
         - name: <name>
           title: <Title>
           iam_api_key_value:
             required: true
       

     • storagebucketvalue: Object Storage bucket.

       user_values:
         - name: <name>
           title: <Title>
           storage_bucket_value:
             required: true
       

     • prometheusworkspaceidvalue: Prometheus workspace name.

       user_values:
         - name: <name>
           title: <Title>
           prometheus_workspace_id_value:
             required: false
       

     • licenseidvalue: Subscription ID from the License Manager API.

       user_values:
         - name: <name>
           title: <Title>
           license_id_value:
             required: false
       

5. private_artifacts: Optional parameter. Use it to avoid moving all the images that come with the product from the publisher's registry to the public yc-marketplace registry. The possible values are true and false; the default one is false.

   This parameter is set for a product version. To install a version with private_artifacts = true, the user will need to utilize Yandex Cloud interfaces. Installation with the helm install command will not be available.

   Access to download components published in the product card's Product contents section will be granted only to the service account under which the user is installing the product. If the user deletes the product, Marketplace will revoke access from the service account.

The variable values specified by the user when installing the product in a Kubernetes cluster will override the values from the values.yaml file.

Example of a product specification and its respective variable fileExample of a product specification and its respective variable file

Product specificationProduct specification

name: "our-app" 

helm_charts:
  - name: cr.yandex/b1gq90dgh25bebiu75o/Vendor/Product/chart
    tag: 1.0-0
    images:
      - registry: app1.image.registry
        name_without_registry: app1.image.name
        tag: app1.image.tag
      - name_with_registry: app2.config.image.name
        tag: app2.config.image.tag
      - full: another-whatever-key.subkey.name    
    reuse_values: true

requirements:
  min_k8s_version: ">=1.18"

# Configurable parameters that might be changed by end user during installation of product. Should be presented in values.yaml
# Supported types: integer, boolean, string, string selector, integer selector.
user_values:
  - name: app.port
    title:
      en: Application port
      ru: Application port
    description:
      en: Port that application will listen to
      ru: Port on which the application accepts incoming requests
    integer_value:
      default_value: 8080
      required: true
      restrictions:
        min: 8000
        max: 9000
  - name: app.tls.use
    title:
      en: TLS
      ru: TLS
    description:
      en: Use TLS
      ru: Use TLS
    boolean_value:
      default_value: true
  - name: app.admin.password
    title:
      en: Admin password
      ru: Admin password
    description:
      en: Password of administrator, should be at least 8 symbols
      ru: Password of administrator, should be at least 8 symbols
    string_value:
      required: true
      secret: true
      length_restrictions:
        min: 8
        max: 20
  - name: app.selector.string
    title:
      en: Custom string selector
      ru: String option
    description:
      en: One value string selector
      ru: Selecting a single string value
    string_selector_value:
      default_value: opt1
      required: true
      values:
        - opt1
        - opt2
        - opt3
  - name: app.selector.integer
    title:
      en: Custom integer selector
      ru: Number option
    description:
      en: One value integer selector
      ru: Selecting a single integer value
    integer_selector_value:
      default_value: 1
      required: true
      values:
        - 1
        - 2
        - 3

# Optional: if set to `true`, the Helm chart and Docker images will not be placed in a public repo.
# This will make the product only installable via Marketplace (and not with `helm install ...`).
private_artifacts: false

# Link to helm chart in publisher registry.
helm_chart:
  name: cr.yandex/b1gq90dgh25bebiu75o/Vendor/Product/chart
  tag: 1.0-0

# Required parameters.
requirements:
  k8s_version: ">=1.18"

images:
  - registry: app1.image.registry
    name_without_registry: app1.image.name
    tag: app1.image.tag
  - name_with_registry: app2.config.image.name
    tag: app2.config.image.tag
  - full: another-whatever-key.subkey.name

# Configurable parameters that might be changed by end user during installation of product. Should be presented in values.yaml
# Supported types: integer, boolean, string, string selector, integer selector.
user_values:
  - name: app.port
    title:
      en: Application port
      ru: Порт приложения
    description:
      en: Port that application will listen to
      ru: Порт, на котором приложение принимает входящие запросы
    integer_value:
      default_value: 8080
      required: true
      restrictions:
        min: 8000
        max: 9000
  - name: app.tls.use
    title:
      en: TLS
      ru: TLS
    description:
      en: Use TLS
      ru: Использовать TLS
    boolean_value:
      default_value: true
  - name: app.admin.password
    title:
      en: Admin password
      ru: Пароль администратора
    description:
      en: Password of administrator, should be at least 8 symbols
      ru: Пароль администратора, должен быть длиной не менее 8 символов
    string_value:
      required: true
      secret: true
      length_restrictions:
        min: 8
        max: 20
  - name: app.selector.string
    title:
      en: Custom string selector
      ru: Строковая опция
    description:
      en: One value string selector
      ru: Выбор одного строкового значения
    string_selector_value:
      default_value: opt1
      required: true
      values:
        - opt1
        - opt2
        - opt3
  - name: app.selector.integer
    title:
      en: Custom integer selector
      ru: Числовая опция
    description:
      en: One value integer selector
      ru: Выбор одного integer значения
    integer_selector_value:
      default_value: 1
      required: true
      values:
        - 1
        - 2
        - 3

# Optional: if set to `true`, the Helm chart and Docker images will not be placed in a public repo.
# This will make the product only installable via Marketplace (and not with `helm install ...`).
private_artifacts: false

values.yaml variable filevalues.yaml variable file

# An example of values.yaml related to publisher manifest above.
replicaCount: 1
podAnnotations: {}
podSecurityContext: {}
...
app1:
  image:
    registry: cr.yandex/b1gq90dgh25bebiu75o/
    name: service-images/application-1
    tag: 1.0
app2:
  name: application-name
  config:
    # image can be declared on any level
    image:
      name: cr.yandex/b1gq90dgh25bebiu75o/service-images/application-2
      tag: 2.0
    pullPolicy: IfNotPresent
another-whatever-key: # key name is not fixed
  subkey:
    name: cr.yandex/b1gq90dgh25bebiu75o/service-images/application-3:3.0
...

# values
app:
  port: 80
  tls:
    use: true
  admin:
    password: ""
  selector:
    string: "opt1"
    integer: 1