Skip to main content
Service Catalog Version 0.78.1

Kubernetes Service

View SourceFiltered Release Notes

Overview​

This service contains Terraform code to deploy your web application containers using the k8-service Gruntwork Helm Chart on to Kubernetes following best practices.

Kubernetes Service architectureKubernetes Service architecture

Features​

  • Deploy your application containers on to Kubernetes
  • Zero-downtime rolling deployments
  • Auto scaling and auto healing
  • Configuration management and Secrets management
  • Ingress and Service endpoints
  • Service discovery with Kubernetes DNS
  • Managed with Helm

Learn​

note

This repo is a part of the Gruntwork Service Catalog, a collection of reusable, battle-tested, production ready infrastructure code. If you’ve never used the Service Catalog before, make sure to read How to use the Gruntwork Service Catalog!

Under the hood, this is all implemented using Terraform modules from the Gruntwork helm-kubernetes-services repo. If you are a subscriber and don’t have access to this repo, email support@gruntwork.io.

Core concepts​

Repo organization​

  • modules: the main implementation code for this repo, broken down into multiple standalone, orthogonal submodules.
  • examples: This folder contains working examples of how to use the submodules.
  • test: Automated tests for the modules and examples.

Deploy​

Non-production deployment (quick start for learning)​

If you just want to try this repo out for experimenting and learning, check out the following resources:

  • examples/for-learning-and-testing folder: The examples/for-learning-and-testing folder contains standalone sample code optimized for learning, experimenting, and testing (but not direct production usage).

Production deployment​

If you want to deploy this repo in production, check out the following resources:

Reference​

  • alb_acm_certificate_arns — A list of ACM certificate ARNs to attach to the ALB. The first certificate in the list will be added as default certificate.
  • alb_health_check_path — URL path for the endpoint that the ALB health check should ping. Defaults to /.
  • alb_health_check_protocol — Protocol (HTTP or HTTPS) that the ALB health check should use to connect to the application container.
  • alb_health_check_success_codes — The HTTP status code that should be expected when doing health checks against the specified health check path. Accepts a single value (200), multiple values (200,201), or a range of values (200-300).
  • alb_health_check_timeout — The timeout, in seconds, during which no response from a target means a failed health check.
  • application_name — The name of the application (e.g. my-service-stage). Used for labeling Kubernetes resources.
  • configmaps_as_env_vars — Kubernetes ConfigMaps to be injected into the container. Each entry in the map represents a ConfigMap to be injected, with the key representing the name of the ConfigMap. The value is also a map, with each entry corresponding to an entry in the ConfigMap, with the key corresponding to the ConfigMap entry key and the value corresponding to the environment variable name.
  • configmaps_as_volumes — Kubernetes ConfigMaps to be injected into the container as volume mounts. Each entry in the map represents a ConfigMap to be mounted, with the key representing the name of the ConfigMap and the value representing a file path on the container to mount the ConfigMap to.
  • container_port — The port number on which this service's Docker container accepts incoming traffic.
  • custom_resources — The map that lets you define Kubernetes resources you want installed and configured as part of the chart.
  • domain_name — The domain name for the DNS A record to bind to the Ingress resource for this service (e.g. service.foo.com). Depending on your external-dns configuration, this will also create the DNS record in the configured DNS service (e.g., Route53).
  • eks_iam_role_for_service_accounts_config — Configuration for using the IAM role with Service Accounts feature to provide permissions to the applications. This expects a map with two properties: `openid_connect_provider_arn and [``openid_connect_provider_url](#openid_connect_provider_url). The `openid_connect_provider_arn is the ARN of the OpenID Connect Provider for EKS to retrieve IAM credentials, while [``openid_connect_provider_url](#openid_connect_provider_url) is the URL. Leave as an empty string if you do not wish to use IAM role with Service Accounts.
  • enable_liveness_probe — Whether or not to enable liveness probe. Liveness checks indicate whether or not the container is alive. When these checks fail, the cluster will automatically rotate the Pod.
  • enable_readiness_probe — Whether or not to enable readiness probe. Readiness checks indicate whether or not the container can accept traffic. When these checks fail, the Pods are automatically removed from the Service (and added back in when they pass).
  • env_vars — A map of environment variable name to environment variable value that should be made available to the Docker container.
  • expose_type — How the service will be exposed in the cluster. Must be one of external (accessible over the public Internet), internal (only accessible from within the same VPC as the cluster), cluster-internal (only accessible within the Kubernetes network).
  • force_destroy_ingress_access_logs — A boolean that indicates whether the access logs bucket should be destroyed, even if there are files in it, when you run Terraform destroy. Unless you are using this bucket only for test purposes, you'll want to leave this variable set to false.
  • horizontal_pod_autoscaler — Configure the Horizontal Pod Autoscaler information for the associated Deployment. HPA is disabled when this variable is set to null.
  • iam_policy — An object defining the policy to attach to `iam_role_name if the IAM role is going to be created. Accepts a map of objects, where the map keys are sids for IAM policy statements, and the object fields are the resources, actions, and the effect ("Allow" or "Deny") of the statement. Ignored if [``iam_role_arn](#iam_role_arn) is provided. Leave as null if you do not wish to use IAM role with Service Accounts.
  • iam_role_exists — Whether or not the IAM role passed in `iam_role_name` already exists. Set to true if it exists, or false if it needs to be created. Defaults to false.
  • iam_role_name — The name of an IAM role that will be used by the pod to access the AWS API. If `iam_role_exists` is set to false, this role will be created. Leave as an empty string if you do not wish to use IAM role with Service Accounts.
  • ingress_access_logs_s3_prefix — The prefix to use for ingress access logs associated with the ALB. All logs will be stored in a key with this prefix. If null, the application name will be used.
  • ingress_backend_protocol — The protocol used by the Ingress ALB resource to communicate with the Service. Must be one of HTTP or HTTPS.
  • ingress_group — Assign the ingress resource to an IngressGroup. All Ingress rules of the group will be collapsed to a single ALB. The rules will be collapsed in priority order, with lower numbers being evaluated first.
  • ingress_path — Path prefix that should be matched to route to the service. For Kubernetes Versions <1.19, Use /* to match all paths. For Kubernetes Versions >=1.19, use / with ingress_path_type set to Prefix to match all paths.
  • ingress_target_type — Controls how the ALB routes traffic to the Pods. Supports 'instance' mode (route traffic to NodePort and load balance across all worker nodes, relying on Kubernetes Service networking to route to the pods), or 'ip' mode (route traffic directly to the pod IP - only works with AWS VPC CNI). Must be set to 'ip' if using Fargate. Only used if expose_type is not cluster-internal.
  • liveness_probe_port — Port that the liveness probe should use to connect to the application container.
  • liveness_probe_protocol — Protocol (HTTP or HTTPS) that the liveness probe should use to connect to the application container.
  • namespace — The Kubernetes Namespace to deploy the application into.
  • override_chart_inputs — Override any computed chart inputs with this map. This map is shallow merged to the computed chart inputs prior to passing on to the Helm Release. This is provided as a workaround while the terraform module does not support a particular input value that is exposed in the underlying chart. Please always file a GitHub issue to request exposing additional underlying input values prior to using this variable.
  • readiness_probe_port — Port that the readiness probe should use to connect to the application container.
  • readiness_probe_protocol — Protocol (HTTP or HTTPS) that the readiness probe should use to connect to the application container.
  • scratch_paths — Paths that should be allocated as tmpfs volumes in the Deployment container. Each entry in the map is a key value pair where the key is an arbitrary name to bind to the volume, and the value is the path in the container to mount the tmpfs volume.
  • secrets_as_env_vars — Kubernetes Secrets to be injected into the container. Each entry in the map represents a Secret to be injected, with the key representing the name of the Secret. The value is also a map, with each entry corresponding to an entry in the Secret, with the key corresponding to the Secret entry key and the value corresponding to the environment variable name.
  • secrets_as_volumes — Kubernetes Secrets to be injected into the container as volume mounts. Each entry in the map represents a Secret to be mounted, with the key representing the name of the Secret and the value representing a file path on the container to mount the Secret to.
  • service_account_name — The name of a service account to create for use with the Pods. This service account will be mapped to the IAM role defined in `var.iam_role_name` to give the pod permissions to access the AWS API. Must be unique in this namespace. Leave as an empty string if you do not wish to assign a Service Account to the Pods.
  • service_port — The port to expose on the Service. This is most useful when addressing the Service internally to the cluster, as it is ignored when connecting from the Ingress resource.
  • sidecar_containers — Map of keys to container definitions that allow you to manage additional side car containers that should be included in the Pod. Note that the values are injected directly into the container list for the Pod Spec.
  • termination_grace_period_seconds — Grace period in seconds that Kubernetes will wait before terminating the pod. The timeout happens in parallel to preStop hook and the SIGTERM signal, Kubernetes does not wait for preStop to finish before beginning the grace period.
  • values_file_path — A local file path where the helm chart values will be emitted. Use to debug issues with the helm chart values. Set to null to prevent creation of the file.
  • wait — When true, wait until Pods are up and healthy or wait_timeout seconds before exiting terraform.
  • wait_timeout — Number of seconds to wait for Pods to become healthy before marking the deployment as a failure.