Skip to content

Latest commit

 

History

History
134 lines (103 loc) · 8.87 KB

environment.md

File metadata and controls

134 lines (103 loc) · 8.87 KB
Raw

Environment

An environment is a Kuberpult concept that describes the target of deployments. Essentially, it is a set of machines where your microservices will run. In practice, an environment in kuberpult corresponds 1:1 to a kubernetes cluster (for example on GCP). An environment is the set of machines where your microservices will run.

For example: development, staging and production are typical environments. When using environment groups, typical examples are de-prod, jp-prod, and pt-prod which would all be production environments - and belong to the production environment group - but are machines in different countries.

Environment Config

In a cloud provider like GCP, we recommend separating the environments on a project level. This means that one GCP project correlates to one Kuberpult environment 1:1 - although this is not a technical requirement.

Environments are also called stages - but in Kuberpult we stick to environments, in short envs.

The config for an environment is stored in a json file called config.json. This file belongs in the environment's directory like this: environments/development/config.json (in this example the config.json file would dictate the configuration for the development environment).

In the config.json file there are 3 main fields:

Upstream:

The "upstream" field can have one of the two options (cannot have both):

  • latest: can only be set to true which means that Kuberpult will deploy the latest version of an application to this environment
  • environment: has a string which is the name of another environment. Following the chain of upstream environments would take you to the one with "latest": true. This is used in release trains: when a release train is run in an environment, it will pull the version from the environment's upstream environment.
Argo CD:

The "argocd" field has a few subfields:

  • "accessList":
    Is a list of objects that describe which resources are allowed in the cluster (Argo CD Docs). Note that this is only necessary when Argo CD cannot apply a certain resource on the cluster. Most common resources (Pods, Configmaps, Cronjobs, Deployments...) just work out of the box. It has the following fields:

    • "group": relates to the Kubernetes API group without the version
    • "kind": the resource type in kubernetes

  • "destination" (Mandatory):

    Defines which Kubernetes cluster/namespace to deploy to

    - Template Argo CD Docs

    It has the following fields:

    • "name" (Mandatory): Name of the cluster (within Argo CD) to deploy to

    • "server" (Mandatory): API Server URL for the cluster (Example: "https://kubernetes.default.svc")

    • "namespace": Target namespace in which to deploy the manifests from source (Example: "my-app-namespace")

      Usually you want to use the same namespace for Applications and AppProjects. For this, use the field "namespace".

      We also allow to use different namespaces for Applications and AppProjects. In that case don't use namespace, use appProjectNamespace and applicationNamespace instead.

    • "appProjectNamespace": defines the namespaces allowed to deploy in the project. Example:

        # Do not allow any app to be installed in `kube-system`  
    - namespace: '!kube-system'

    • "applicationNamespace": This sets the default namespace to deploy a resource in the application if no namespace is defined on the resource's manifests. Example:

        # Destination cluster and namespace to deploy the application
  destination:
    server: https://kubernetes.default.svc
    # The namespace will only be set for namespace-scoped resources that have not set a value for .metadata.namespace
    namespace: guestbook

  • "syncWindows":

    Sync windows are configurable windows of time where syncs will either be blocked or allowed. Note that this is not generally necessary, and by default, Argo CD syncs all the time. We recommend to only use this setting, if it's really necessary, as it complicates the deployment pipeline.

    It has the following fields:

    • "schedule": is the schedule of the window in cron format (Example: "10 1 * * *")
    • "duration": the duration of the window (Example: "1h")
    • "kind": defines whether the sync is allowed ("allow") or denied ("deny")
    • "applications": an array with the names of the applications

  • "ignoreDifferences":

    Argo CD allows ignoring differences at a specific JSON path, using RFC6902 JSON patches and JQ path expressions.

    Application Level Config Argo CD Docs

    It has the following fields:

    • "group": relates to the Kubernetes API group without the version
    • "kind": the resource type in kubernetes
    • "name": application name
    • "namespace": namespace in the cluster
    • "jsonPointers": is a list of strings that is used to configure which fields should be ignored when comparing differences (Example: - /spec/replicas would ignore differences in spec.replicas which is useful when we don't want to sync fields that change overtime but don't need a sync)
    • "jqPathExpressions": is a list of strings that can be used to ignore elements of a list by identifying list items based of item content (Example: - .spec.template.spec.initContainers[] | select(.name == "injected-init-container")) (JQ Docs)
    • "managedFieldsManagers": is a list of string which can be used to ignore fields owned by specific managers defined in your live resources (Example: - kube-controller-manager)

  • "applicationAnnotations": Map of annotations to add to the resources

  • "syncOptions": A list of strings that allows users to customize some aspects of how it syncs the desired state in the target cluster (Sync Options Argo CD Docs)

Environment Group:

The "environmentGroup" field is a string that defines which environment group the environment belongs to (Example: Production can be an environment group to group production environments in different countries). EnvironmentGroups are still in development. We'll update this section once they are ready. The goal of EnvironmentGroups is to make handling of many similar clusters easier. They will also work with Release Trains.

Environment Creation

Kuberpult offers an API endpoint for environment creation. This endpoint is expecting the following information:

  • IAP Token:
    • If IAP is enabled ( in helm: ingress.iap.enabled: false) You need to provide kuberpult with your own IAP access token. We use google cloud authentication in order generate it. For more information on programmatic authentication, please refere to this resource.
  • Environment Name
    • The name of the environment you are trying to create.
  • Configuration Data:
    • You need to provide some configuration specifications to your environment. The provided data must be in JSON format. This previous section goes into detail regarding the information that must be contained within your configuration file. You can find an example file here.
curl -f -X POST -H "Authorization: Bearer $IAPToken" \
                -H "multipart/form-data" --form-string "config=$DATA" \
                $KUBERPULT_API_URL/environments/$ENVIRONMENT_NAME

Example:

Below you can find an example of the curl request needed to create an environment named staging, accessing a kuberpult instance running locally hearing on port 8081, reading some config.json file from the local filesystem that contains the configuration data. For local development, the IAPToken can be omitted.

DATA=$(cat config.json)
curl -f -X POST -H "multipart/form-data" --form-string "config=$DATA" \
                http://localhost:8081/environments/staging

IMPORTANT

In the past, the common way to change the environment configuration (config.json files) was to directly edit the files in the manifest repo and push. This is no longer recommended and now highly discouraged. Kuberpult should be the only one writing to the manifest repository. Direct manipulation of the manifest repository should be avoided.