Resource Definitions

Driver

Capability

Flavor

Resource Type

Runtime

Connecting to a Git repository (GitOps mode)

This section contains example Resource Definitions for connecting to a Git repository to push application CRs in GitOps mode .

It also provides a solution to specify the non GitOps-cluster where the GitOps deploys workloads.
To retrieve the status of deployed workloads, the Orchestrator searches for a k8s-cluster Resource with the Id k8s-cluster-runtime. If it doesn’t find this resource, it defaults to the k8s-cluster resource with the Id k8s-cluster. When the default cluster is a GitOps-managed cluster, an additional non-GitOps cluster is required to gather runtime information for workloads deployed by the GitOps operator. This example demonstrates that process.

The namespace name where the Orchestrator will look for the Kubernetes objects to gather runtime information is retrieved from the Active Resource of type k8s-namespace. Note that in GitOps mode, the namespace is an externally managed Resource, i.e. the Platform Orchestrator does not create the namespace. It is recommended to use a namespace Resource Definition based on the Echo Driver to reflect this fact. This also means that any customization of the namespace, such as adding specific labels, must be managed externally.

The chart illustrates the setup. Because k8s-cluster is an implicit Resource Type , one such Resource is always matched for any Deployment. This creates the Resource representing the GitOps cluster, using the k8s-cluster-git Driver. That resource co-provisions another Resource of type k8s-cluster with the Id k8s-cluster-runtime and the k8s-cluster-gke Driver, representing the runtime cluster.

flowchart LR
  subgraph implicitResources[Implicit Resources]
    k8s-namespace(id: k8s-namespace<br/>type: k8s-namespace<br/>Driver: echo)
    workload(id: workload<br/>type: workload) ~~~ k8s-cluster-gitops(id: k8s-cluster<br/>type: k8s-cluster<br/>Driver: k8s-cluster-git)
  end
  k8s-cluster-gitops --o|co-provision| k8s-cluster-runtime(id: k8s-cluster-runtime<br/>type: k8s-cluster<br/>Driver: k8s-cluster-gke)
  platformOrchestrator{Platform<br/>Orchestrator} -.->|Deploy K8s CRs to<br/>Git repo through| k8s-cluster-gitops
  platformOrchestrator -.->|Determine<br/>namespace from| k8s-namespace
  platformOrchestrator -.->|Obtain runtime information from| k8s-cluster-runtime

These files make up the example:

  • github-for-gitops.yaml: contains configuration for connecting to a Git repository. This Resource Definition co-provisions a GKE cluster to be used to fetch Runtime Information, the k8s-cluster-runtime Id is used in the co-provision key. This format is for use with the Humanitec CLI.
  • gke-temporary-credentials-runtime.yaml: uses temporary credentials defined via a Cloud Account. The Resource Id specified in the Matching Criteria is k8s-cluster-runtime and it ensures that this Definition will be matched to provision the k8s-cluster Resource co-provisioned by the GitOps cluster Resource Definition. This format is for use with the Humanitec CLI .
    • This runtime Resource Definition can optionally use the Humanitec Agent to access runtime information on a private cluster. This requires the Agent to be configured for being able to access the cluster and the corresponding Agent Resource Definition (next item) being matched in the agent_url property. See the documentation for details.
  • gke-agent.yaml: defines the Resource for the Humanitec Agent . Relevant only if the Agent is being used to access the runtime cluster.
  • custom-namespace.yaml: shows how to use the Echo Driver to return the name of an externally managed namespace that must match the namespace where the GitOps Operator creates the resources. This format is for use with the Humanitec CLI .

Resource Definitions

custom-namespace.yaml ( view on GitHub ) :

apiVersion: entity.humanitec.io/v1b1
kind: Definition
metadata:
  id: namespace-echo
entity:
  name: namespace-echo
  type: k8s-namespace
  driver_type: humanitec/echo
  driver_inputs:
    values:
      namespace: "${context.app.id}-${context.env.id}"
  criteria:
    - {}

github-for-gitops.yaml ( view on GitHub ) :

apiVersion: entity.humanitec.io/v1b1
kind: Definition
metadata:
  id: github-for-gitops
entity:
  name: github-for-gitops
  driver_type: humanitec/k8s-cluster-git
  type: k8s-cluster
  driver_inputs:
    values:
      # Git repository for pushing manifests
      url: [email protected]:example-org/gitops-repo.git
      # When using a GitHub personal access token, use the HTTPS URL:
      # url: https://github.com/example-org/gitops-repo.git
      # Branch in the git repository, optional. If not specified, the default branch is used.
      branch: development
      # Path in the git repository, optional. If not specified, the root is used.
      path: "${context.app.id}/${context.env.id}"
      # Load Balancer, optional. Though it's not related to the GitOps setup, it's used to create ingress in the target K8s cluster if such resources are part of the Resource Graph, just like with a non-GitOps cluster.
      loadbalancer: 35.10.10.10
    secrets:
      credentials:
        ssh_key: my-git-ssh-key
        # Alternative to ssh_key: password or Personal Account Token
        # password: my-git-ssh-pat
  
  # To co-provision a non-GitOps cluster resource from which the Orchestrator will fetch runtime info.
  # The provision key specifies `k8s-cluster-runtime` as Resource Id and it must be used in the non-GitOps cluster resource definition Matching Criteria.
  provision:
    k8s-cluster#k8s-cluster-runtime:
      is_dependent: false
      match_dependents: false

gke-agent.yaml ( view on GitHub ) :

# This Resource Definition describes the Humanitec Agent to match for the runtime cluster
# if the Agent is being used
apiVersion: entity.humanitec.io/v1b1
kind: Definition
metadata:
  id: gke-agent
entity:
  type: agent
  name: gke-agent
  driver_type: humanitec/agent
  driver_inputs:
    values:
      # This property must match the Agent id as it is configured in the Platform Orchestrator
      id: gke-agent
  # Set matching criteria so that it is matched along with the runtime cluster Resource Definition
  criteria:
  - env_type: development
    res_id: agent

gke-temporary-credentials-runtime.yaml ( view on GitHub ) :

# Connect to a GKE cluster using temporary credentials defined via a Cloud Account
apiVersion: entity.humanitec.io/v1b1
kind: Definition
metadata:
  id: gke-temporary-credentials
entity:
  name: gke-temporary-credentials
  type: k8s-cluster
  # The driver_account references a Cloud Account of type "gcp-identity"
  # which needs to be configured for your Organization.
  driver_account: gcp-temporary-creds
  driver_type: humanitec/k8s-cluster-gke
  driver_inputs:
    values:
      loadbalancer: 35.10.10.10
      name: demo-123
      zone: europe-west2-a
      project_id: my-gcp-project
    secrets:
      # Optional: set this property to use the Humanitec Agent for accessing runtime information
      # if the target cluster is private. This requires the Agent to be configured
      # for the cluster and the proper Agent Resource Definition to be matched.
      agent_url: "${resources['agent#agent'].outputs.url}"
  criteria:
  - res_id: k8s-cluster-runtime

custom-namespace.tf ( view on GitHub ) :

resource "humanitec_resource_definition" "namespace-echo" {
  driver_type = "humanitec/echo"
  id          = "namespace-echo"
  name        = "namespace-echo"
  type        = "k8s-namespace"
  driver_inputs = {
    values_string = jsonencode({
      "namespace" = "$${context.app.id}-$${context.env.id}"
    })
  }
}

resource "humanitec_resource_definition_criteria" "namespace-echo_criteria_0" {
  resource_definition_id = resource.humanitec_resource_definition.namespace-echo.id

}

github-for-gitops.tf ( view on GitHub ) :

resource "humanitec_resource_definition" "github-for-gitops" {
  driver_type = "humanitec/k8s-cluster-git"
  id          = "github-for-gitops"
  name        = "github-for-gitops"
  type        = "k8s-cluster"
  driver_inputs = {
    values_string = jsonencode({
      "url"          = "[email protected]:example-org/gitops-repo.git"
      "branch"       = "development"
      "path"         = "$${context.app.id}/$${context.env.id}"
      "loadbalancer" = "35.10.10.10"
    })
    secrets_string = jsonencode({
      "credentials" = {
        "ssh_key" = "my-git-ssh-key"
      }
    })
  }

  provision = {
    "k8s-cluster#k8s-cluster-runtime" = {
      is_dependent     = false
      match_dependents = false
    }
  }
}

gke-agent.tf ( view on GitHub ) :

resource "humanitec_resource_definition" "gke-agent" {
  driver_type = "humanitec/agent"
  id          = "gke-agent"
  name        = "gke-agent"
  type        = "agent"
  driver_inputs = {
    values_string = jsonencode({
      "id" = "gke-agent"
    })
  }
}

resource "humanitec_resource_definition_criteria" "gke-agent_criteria_0" {
  resource_definition_id = resource.humanitec_resource_definition.gke-agent.id
  env_type               = "development"
  res_id                 = "agent"
}

gke-temporary-credentials-runtime.tf ( view on GitHub ) :

resource "humanitec_resource_definition" "gke-temporary-credentials" {
  driver_type    = "humanitec/k8s-cluster-gke"
  id             = "gke-temporary-credentials"
  name           = "gke-temporary-credentials"
  type           = "k8s-cluster"
  driver_account = "gcp-temporary-creds"
  driver_inputs = {
    values_string = jsonencode({
      "loadbalancer" = "35.10.10.10"
      "name"         = "demo-123"
      "zone"         = "europe-west2-a"
      "project_id"   = "my-gcp-project"
    })
    secrets_string = jsonencode({
      "agent_url" = "$${resources['agent#agent'].outputs.url}"
    })
  }
}

resource "humanitec_resource_definition_criteria" "gke-temporary-credentials_criteria_0" {
  resource_definition_id = resource.humanitec_resource_definition.gke-temporary-credentials.id
  res_id                 = "k8s-cluster-runtime"
}