Customize your namespace

This page is a chapter of the Quickstart learning path. Make sure to progress through the chapters in the order set in the main navigation. To start out, go to Introduction.

Configure the Orchestrator #

The deployment worked, but the created namespace name - a GUID - is not great for human readability.

Let’s change the Orchestrator’s behavior regarding namespaces. Similar to the cluster, you do that by providing another Resource Definition, this time of the type k8s-namespace.

Download this example Resource Definition from Github:

curl -fLO https://raw.githubusercontent.com/humanitec-architecture/example-library/main/resource-definitions/template-driver/namespace/custom-namespace.yaml

Edit the contents of custom-namespace.yaml:

• Change both id and name to quickstart-namespace
• Remove the labels section inside the manifests

This Resource Definition uses the Template Driver (driver_type: humanitec/template). It is a generic Driver that can essentially generate and apply any manifest to the target Kubernetes cluster. In the current scenario, we use it to dynamically construct a namespace name and then apply a manifest of kind: namespace.

The name of the namespace is being constructed from the context using specific placeholders. You can see that the name is built from two variables that are fetched from the context:

name: ${context.env.id}-${context.app.id}

For the Deployment as you performed it, the Environment id is development and the app is quickstart. The order of the two obviously helps you either find “all environments of a type” or “all instances of an app” on your cluster faster.

The next thing to adjust is the criteria or matching criteria. This is an empty object at the moment, which means “match to everything unless specified more precisely”. Leave this part as it is.

criteria:
  - {}

If you want to check for correctness of your edits or skip the self-editing, you can find a preconfigured file in the solutions subdirectory. To use it, execute:

cp solutions/custom-namespace.yaml custom-namespace.yaml

Apply the namespace Resource Definition to the Orchestrator:

humctl apply -f custom-namespace.yaml

Apply the new configuration #

To change to the new namespace naming scheme, all you need to do is redeploy the Workload by re-executing this command:

humctl score deploy --wait

The Orchestrator will use the newly provided namespace Resource Definition and deploy your application into a fresh namespace with the name as per the convention you created. Verify the result using the same commands as before:

export NAMESPACE_DEVELOPMENT=$(humctl get active-resource \
  /orgs/${HUMANITEC_ORG}/apps/${HUMANITEC_APP}/envs/${HUMANITEC_ENV}/resources \
  -oyaml \
  | yq -r '.[] | select (.metadata.type == "k8s-namespace") | .status.resource.namespace')

echo $NAMESPACE_DEVELOPMENT

The Application namespace is now named development-quickstart according to the pattern defined in the Resource Definition.

Your first deployment used the pre-configured Default Humanitec Namespace Resource Definition of type k8s-namespace which uses the GUID-style naming. Those Resource Definitions serve as a fallback whenever no other match is found.

Inspect the Kubernetes objects in that new namespace. They should look just like before:

kubectl get all -n $NAMESPACE_DEVELOPMENT

Quick resource theory #

The power behind that concept comes from detaching the “ask” for a resource from the actual implementation. While the Score file captures the needs of the application as specified by the developer, the configuration of the Orchestrator captures how this is implemented as specified by the platform engineers. The Orchestrator’s automation allows both sides to evolve independently from each other while maintaining developer self-service.

The matching criteria allow you to specify per context how a specific resource is provided - a database in a development environment might look very different from one in a production environment, but as both conform to the interface specification of that database type, the developer doesn’t need to care as long as the runtime context is configuring his application correctly to connect to the database instance.

Recap #

And that concludes this chapter. You have:

• ✅ Created a Resource Definition for custom namespaces
• ✅ Applied the Resource Definition to the Platform Orchestrator
• ✅ Used the Resource Definition in your next Deployment
• ✅ Verified the adjusted result on the Kubernetes end

Your setup now looks like this:

%%{ init: { 'flowchart': { 'curve': 'linear' } } }%%
flowchart LR
  subgraph scoreFile[Score file]
    scoreWorkload(Workload)
  end
  subgraph platformOrchestrator[Platform Orchestrator]
    cloudAccount(Cloud Account)
    resDefCluster(Resource Definition\nCluster)
    subgraph application[Application]
        envDevelopment(Environment\n"development")
    end
    resDefNamespace(Resource Definition\nNamespace)
  end
  subgraph cloudInfrastructure[Cloud Infrastructure]
    subgraph k8sCluster[Kubernetes Cluster]
      subgraph namespace[Pretty namespace]
        workload(Workload)
      end
    end
  end
  scoreFile -->|humctl score deploy| envDevelopment
  resDefCluster -.- k8sCluster
  envDevelopment --> namespace
  resDefNamespace -.- namespace

  %% Using the predefined styles
  class application,k8sCluster nested
  class resDefNamespace,namespace highlight

Continue to expand your Application into a new Environment.