Import an existing service with `kix.mkImport`

This content is for the v0.1 version. Switch to the latest version for up-to-date documentation.

This guide assumes the Service already exists and its name, namespace, and port are stable. Use an import when another system owns that Service and Kix packages need its connection details.

Declare the import

Add an instance whose package is created with kix.mkImport:

            package = kix.mkImport {
              kind = "Service";
              apiVersion = "v1";
              out = {
                name = "legacy-api";
                fqdn = "legacy-api.legacy.svc.cluster.local";
                port = 8080;
              };
            };
            aliases = [ "legacyApi" ];

View source on GitHub ↗

Set kind and apiVersion to describe the existing resource. The out attributes form the interface that consuming packages receive. They must match the Service in the target cluster.

Kix verifies the imported object’s kind, API version, name, and namespace before deployment. It does not verify the fqdn or port outputs. Those values pass through unchanged, so an incorrect port can deploy successfully and fail only at runtime.

The legacyApi alias lets a package request this import with a build argument of the same name. Choose an alias that describes the dependency’s role rather than its location. If the import provides one of Kix’s registered infrastructure roles, such as dns, declare it with roles = [ "dns" ] instead. The role name also acts as the dependency key. An imported role is a weak provider, so a managed instance that claims the same role takes precedence.

An out.fqdn written as a string literal carries no information about the Service behind it. A workload that uses the address gets a dependency edge, but Kix cannot derive an egress rule. On a cluster with generated network policy the call is dropped at runtime while kix check stays green.

Describe the Service instead of asserting its address, and let Kix derive the address from the description:

package = kix.mkImport {
  kind = "Service";
  apiVersion = "v1";
  from =
    { scope, ... }:
    {
      build =
        { self, ... }:
        {
          service = scope.mkResource {
            apiVersion = "v1";
            kind = "Service";
            name = "legacy-api";
            spec = {
              selector."app.kubernetes.io/name" = "legacy-api";
              ports = [
                {
                  port = 8080;
                  protocol = "TCP";
                }
              ];
            };
          };

          root = self.service;
        };
    };
};

Kix still does not render the Service. It uses this description to derive out.fqdn and identify the pods reached through that address. The policy generator needs both pieces of information. Make sure the selector matches the live Service.

Use the imported outputs

Accept the alias as a package build argument and read the values you need:

      clientConfig = scope.mkResource {
        apiVersion = "v1";
        kind = "ConfigMap";
        name = "legacy-api-client";
        data.endpoint = "http://${legacyApi.out.fqdn}:${toString legacyApi.out.port}";
      };

      root = self.clientConfig;

View source on GitHub ↗

This example writes the imported endpoint into a client ConfigMap. A workload could use the same values in environment variables or generated configuration.

Check the cluster

Evaluate the cluster before deploying it:

Run in kix-examples/

❱ kix check how-to-adoption
 TOOL         RESULT  DETAILS                                                       
 eval         pass    20 manifests evaluated                                        
 kubeconform  pass    skipped (this validation tool is not yet integrated with Kix) 
 pluto        pass    skipped (this validation tool is not yet integrated with Kix) 
 kyverno      pass    skipped (this validation tool is not yet integrated with Kix) 
 scorecard    pass    0 errors, 14 warnings, 4 info

Confirm that Kix classifies the instance as an import:

Run in kix-examples/

❱ kix list packages --cluster how-to-adoption
 NAME                 VERSION  STATUS               
 client               1.0.0    installed [apps]     
 helm-web             1.0.0    installed [apps]     
 legacy-api           -        import [legacy]      
 legacy-api-contract  1.0.0    installed [apps]     
 legacy-web           1.0.0    installed [apps]     
 platform-dns         -        import [kube-system] 
 platform-storage     -        import [kube-system]

Render the manifests to verify the value received by the client:

Run in kix-examples/ Output excerpt

❱ kix build how-to-adoption --output json
{
  "apiVersion": "v1",
  "kind": "ConfigMap",
  "metadata": {
    "name": "legacy-api-client",
    "namespace": "apps"
  },
  "data": {
    "endpoint": "http://legacy-api.legacy.svc.cluster.local:8080"
  }
}

Kix renders a PackageInstance marker for legacy-api, but it does not render or update the Service itself. Keep the Service in the lifecycle of the system that already owns it.