Kubernetes Namespace
Overview
This service contains Terraform code to provision a best practices Kubernetes Namespace.
Features
- Target any Kubernetes cluster (e.g., EKS, GKE, minikube, etc)
- Provision a set of default best practices RBAC roles for managing access to the Namespace
- Optionally configure Fargate Profile to schedule all Pods on EKS Fargate
Learn
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 terraform-kubernetes-namespace repo. If you are a subscriber and don’t have access to this repo, email support@gruntwork.io.
Core concepts
-
Official documentation on Namespace: learn about the basics of Kubernetes Namespaces including what they are, how to interact with Namespaces, how DNS works, and when to use Namespaces.
-
Official documentation on RBAC: learn about Kubernetes RBAC including what they are, what resources are involved, how they work, how to bind roles to users, and more.
-
Amazon’s documentation on Fargate: learn about AWS EKS Fargate including what they are, how it works, limitations of Fargate, and more.
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:
- examples/for-production folder: The
examples/for-production
folder contains sample code optimized for direct usage in production. This is code from the Gruntwork Reference Architecture, and it shows you how we build an end-to-end, integrated tech stack on top of the Gruntwork Service Catalog.
Sample Usage
- Terraform
- Terragrunt
# ------------------------------------------------------------------------------------------------------
# DEPLOY GRUNTWORK'S K8S-NAMESPACE MODULE
# ------------------------------------------------------------------------------------------------------
module "k_8_s_namespace" {
source = "git::git@github.com:gruntwork-io/terraform-aws-service-catalog.git//modules/services/k8s-namespace?ref=v0.118.2"
# ----------------------------------------------------------------------------------------------------
# REQUIRED VARIABLES
# ----------------------------------------------------------------------------------------------------
# Name of the Namespace to create.
name = <string>
# ----------------------------------------------------------------------------------------------------
# OPTIONAL VARIABLES
# ----------------------------------------------------------------------------------------------------
# Map of string key default pairs that can be used to store arbitrary metadata
# on the namespace and roles. See the Kubernetes Reference for more info
# (https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/).
annotations = {}
# Name of the EKS cluster where the Namespace will be created. Required when
# var.schedule_pods_on_fargate is `true`.
eks_cluster_name = null
# The list of RBAC entities that should have full access to the Namespace.
full_access_rbac_entities = []
# Map of string key value pairs that can be used to organize and categorize
# the namespace and roles. See the Kubernetes Reference for more info
# (https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/).
labels = {}
# ARN of IAM Role to use as the Pod execution role for Fargate. Required if
# var.schedule_pods_on_fargate is true.
pod_execution_iam_role_arn = null
# The list of RBAC entities that should have read only access to the
# Namespace.
read_only_access_rbac_entities = []
# When true, will create a Fargate Profile that matches all Pods in the
# Namespace. This means that all Pods in the Namespace will be scheduled on
# Fargate. Note that this value is only used if var.kubeconfig_auth_type is
# eks, as Fargate profiles can only be created against EKS clusters.
schedule_pods_on_fargate = false
# The subnet IDs to use for EKS worker nodes. Used when provisioning Pods on
# to Fargate. At least 1 subnet is required if var.schedule_pods_on_fargate is
# true.
worker_vpc_subnet_ids = []
}
# ------------------------------------------------------------------------------------------------------
# DEPLOY GRUNTWORK'S K8S-NAMESPACE MODULE
# ------------------------------------------------------------------------------------------------------
terraform {
source = "git::git@github.com:gruntwork-io/terraform-aws-service-catalog.git//modules/services/k8s-namespace?ref=v0.118.2"
}
inputs = {
# ----------------------------------------------------------------------------------------------------
# REQUIRED VARIABLES
# ----------------------------------------------------------------------------------------------------
# Name of the Namespace to create.
name = <string>
# ----------------------------------------------------------------------------------------------------
# OPTIONAL VARIABLES
# ----------------------------------------------------------------------------------------------------
# Map of string key default pairs that can be used to store arbitrary metadata
# on the namespace and roles. See the Kubernetes Reference for more info
# (https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/).
annotations = {}
# Name of the EKS cluster where the Namespace will be created. Required when
# var.schedule_pods_on_fargate is `true`.
eks_cluster_name = null
# The list of RBAC entities that should have full access to the Namespace.
full_access_rbac_entities = []
# Map of string key value pairs that can be used to organize and categorize
# the namespace and roles. See the Kubernetes Reference for more info
# (https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/).
labels = {}
# ARN of IAM Role to use as the Pod execution role for Fargate. Required if
# var.schedule_pods_on_fargate is true.
pod_execution_iam_role_arn = null
# The list of RBAC entities that should have read only access to the
# Namespace.
read_only_access_rbac_entities = []
# When true, will create a Fargate Profile that matches all Pods in the
# Namespace. This means that all Pods in the Namespace will be scheduled on
# Fargate. Note that this value is only used if var.kubeconfig_auth_type is
# eks, as Fargate profiles can only be created against EKS clusters.
schedule_pods_on_fargate = false
# The subnet IDs to use for EKS worker nodes. Used when provisioning Pods on
# to Fargate. At least 1 subnet is required if var.schedule_pods_on_fargate is
# true.
worker_vpc_subnet_ids = []
}
Reference
- Inputs
- Outputs
Required
name
stringName of the Namespace to create.
Optional
annotations
map(string)Map of string key default pairs that can be used to store arbitrary metadata on the namespace and roles. See the Kubernetes Reference for more info (https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/).
{}
eks_cluster_name
stringName of the EKS cluster where the Namespace will be created. Required when schedule_pods_on_fargate
is true
.
null
full_access_rbac_entities
list(object(…))The list of RBAC entities that should have full access to the Namespace.
list(object({
# The type of entity. One of User, Group, or ServiceAccount
kind = string
# The name of the entity (e.g., the username or group name, depending on kind).
name = string
# The namespace where the entity is located. Only used for ServiceAccount.
namespace = string
}))
[]
Details
The name of the entity (e.g., the username or group name, depending on kind).
Details
The namespace where the entity is located. Only used for ServiceAccount.
labels
map(string)Map of string key value pairs that can be used to organize and categorize the namespace and roles. See the Kubernetes Reference for more info (https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/).
{}
ARN of IAM Role to use as the Pod execution role for Fargate. Required if schedule_pods_on_fargate
is true.
null
read_only_access_rbac_entities
list(object(…))The list of RBAC entities that should have read only access to the Namespace.
list(object({
# The type of entity. One of User, Group, or ServiceAccount
kind = string
# The name of the entity (e.g., the username or group name, depending on kind).
name = string
# The namespace where the entity is located. Only used for ServiceAccount.
namespace = string
}))
[]
Details
The name of the entity (e.g., the username or group name, depending on kind).
Details
The namespace where the entity is located. Only used for ServiceAccount.
When true, will create a Fargate Profile that matches all Pods in the Namespace. This means that all Pods in the Namespace will be scheduled on Fargate. Note that this value is only used if kubeconfig_auth_type
is eks, as Fargate profiles can only be created against EKS clusters.
false
worker_vpc_subnet_ids
list(string)The subnet IDs to use for EKS worker nodes. Used when provisioning Pods on to Fargate. At least 1 subnet is required if schedule_pods_on_fargate
is true.
[]
The name of the created namespace.
The name of the rbac role that grants admin level permissions on the namespace.
The name of the rbac role that grants read only permissions on the namespace.