Skip to main content

Kubernetes

Our integration with Kubernetes queries your Kubernetes clusters directly according to your definition. By using our Kubernetes integration, you can ingest live data directly from your K8s clusters into Port in a transparent, efficient and precise manner, thus making sure only the information you need appears in the software catalog, and remains up to date.

Our integration with Kubernetes provides real-time event processing, this allows for an accurate real-time representation of your K8s cluster inside Port.

tip

Port's Kubernetes exporter is open source, view the source code here

💡 Kubernetes exporter common use cases​

Our Kubernetes exporter makes it easy to fill the software catalog with live data directly from your clusters, for example:

  • Map all the resources in your clusters, including namespaces, pods, replica sets, cluster nodes, deployments and other cluster objects;
  • Get real-time metadata from your cluster such as replica counts, deployment health, node health and more;
  • Use relations to create a complete, easily digestible map of your K8s cluster inside Port;
  • Map your Kubernetes resources from common CRDs such as ArgoCD, Istio and more;
  • etc.

How it works​

Port's Kubernetes exporter allows you to bring all the data supported by the K8s API to show running services, environments and more. The open source Kubernetes exporter allows you to perform extract, transform, load (ETL) on data from K8s into the desired software catalog data model.

The exporter is deployed using a Helm chart installed on the cluster. Once it is set up, it continues to sync changes, meaning that all changes, deletions or additions are accurately and automatically reflected in Port.

The helm chart uses a YAML configuration stored in the integration within your Portal. This configuration describes the ETL process responsible for loading data into the developer portal. The approach reflects a golden middle between an overly opinionated K8s visualization that might not work for everyone and a too-broad approach that could introduce unneeded complexity into the developer portal.

Here is an example snippet from the integration configuration which demonstrates the ETL process for getting ReplicaSet data from the cluster and into the software catalog:

The exporter makes use of the JQ JSON processor to select, modify, concatenate, transform and perform other operations on existing fields and values from the Kubernetes objects.

Exporter JQ configuration​

The exporter configuration is how you specify the exact resources you want to query from your K8s cluster, and also how you specify which entities and which properties you want to fill with data from the cluster.

Here is an example configuration block:

resources: # List of K8s resources to list, watch, and export to Port.
  - kind: apps/v1/replicasets # group/version/resource (G/V/R) format
    selector:
      query: .metadata.namespace | startswith("kube") | not # JQ boolean query. If evaluated to false - skip syncing the object.
    port:
      entity:
        mappings: # Mappings between one K8s object to one or many Port Entities. Each value is a JQ query.
          - identifier: .metadata.name
            title: .metadata.name
            blueprint: '"deploymentConfig"'
            properties:
              creationTimestamp: .metadata.creationTimestamp
              annotations: .metadata.annotations
              status: .status

Exporter configuration structure​

  • The root key of the configuration YAML is the resources key:

    resources:
      - kind: apps/v1/replicasets
        selector:
        ...

  • The kind key is a specifier for an object from the K8s API or CRD following the group/version/resource (G/V/R) format:

      resources:
        - kind: apps/v1/replicasets
          selector:
          ...
    tip

    A reference of available Kubernetes Resources to list, watch, and export can be found here

  • The selector and the query keys let you filter exactly which objects from the specified kind will be ingested to the software catalog

    resources:
      - kind: apps/v1/replicasets
        selector:
          query: .metadata.namespace | startswith("kube") | not # JQ boolean query. If evaluated to false - skip syncing the object.
        port:

    Some example use cases:

    • To sync all objects from the specified kind: do not specify a selector and query key;

    • To sync all objects from the specified kind that are not related to the internal Kubernetes system, use:

      query: .metadata.namespace | startswith("kube") | not

    • To sync all objects from the specified kind that start with production, use:

      query: .metadata.namespace | startswith("production")

    • etc.

  • The port, entity and the mappings keys open the section used to map the Kubernetes object fields to Port entities, the mappings key is an array where each object matches the structure of an entity

    resources:
      - kind: apps/v1/replicasets
        selector:
          query: .metadata.namespace | startswith("kube") | not
        port:
          entity:
            mappings: # Mappings between one K8s object to one or many Port Entities. Each value is a JQ query.
              - identifier: .metadata.name
                title: .metadata.name
                blueprint: '"myBlueprint"'
                properties:
                  creationTimestamp: .metadata.creationTimestamp
                  annotations: .metadata.annotations
                  status: .status
                relations:
                  myRelation: .metadata.namespace

Prerequisites​

  • Port's Kubernetes exporter is installed using Helm, so Helm must be installed to use the exporter's chart. Please refer to Helm's documentation for installation instructions;
  • You will need your Port credentials to install the Kubernetes exporter.
tip
Get your Port credentials

To get your Port credentials, go to your Port application, click on the ... button in the top right corner, and select Credentials. Here you can view and copy your CLIENT_ID and CLIENT_SECRET:

info

The exporter helm chart can be found here

Installation​

Choose one of the following installation methods:

  1. Add Port's Helm repo by using the following command:

    helm repo add port-labs https://port-labs.github.io/helm-charts
    tip

    If you already added Port's Helm repo earlier, run helm repo update to retrieve the latest versions of the charts. You can then run helm search repo port-labs to see the charts.

  2. Install the exporter service on your Kubernetes cluster by running the following command:

     helm upgrade --install my-port-k8s-exporter port-labs/port-k8s-exporter \
         --create-namespace --namespace port-k8s-exporter \
         --set secret.secrets.portClientId=YOUR_PORT_CLIENT_ID \
         --set secret.secrets.portClientSecret=YOUR_PORT_CLIENT_SECRET \
         --set portBaseUrl='https://api.getport.io' \
         --set stateKey="k8s-exporter"  \
         --set eventListener.type="POLLING"  \
         --set "extraEnv[0].name"="CLUSTER_NAME" \
         --set "extraEnv[0].value"=YOUR_PORT_CLUSTER_NAME
Selecting a Port API URL by account region

The baseUrl, port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters are used to select which instance or Port API will be used.

Port exposes two API instances, one for the EU region of Port, and one for the US region of Port.

info

By default, the exporter will try to initiate pre-defined blueprints and resource mapping.

Done! The exporter will begin creating and updating objects from Kubernetes cluster as Port entities shortly.

Updating exporter configuration​

To update the exporter resource mapping, open the data sources page in Port and click on your Kubernetes integration. Then edit the exporter configuration and click on the Save & Resync button.

Examples​

Refer to the examples page for practical configurations and their corresponding blueprint definitions.

Advanced​

Refer to the advanced page for advanced use cases and outputs.