Space Tutorial
Introduction ¶
Welcome to the Nauticus tutorial page! Here, you will learn about the powerful features of Nauticus, a Kubernetes controller that simplifies the management of spaces within your cluster. Spaces are fully-managed namespaces that integrate with RBAC, network policies, resources, and quotas. With Nauticus, you can easily create, update, and delete spaces, as well as manage additional resources such as service accounts and limit ranges. This tutorial will guide you through the process of using Nauticus to manage your spaces and resources, and provide examples of how to utilize its features to improve your workflow. Let's get started!
Specify Space's owner(s) ¶
In the Nauticus controller, you have the option to specify the owner(s) of a space. This allows you to assign specific users or teams to be responsible for managing the resources within a particular space. This feature is particularly useful in a multi-tenant environment, where different teams may be responsible for different parts of the application.
To specify the owner(s) of a space, you can add the "owners" field in the space specification. The field should contain a list of email addresses of the users or teams that will be designated as the owner(s) of the space. For example, if you want to assign the space to the team dev-team@example.com, the space specification would look like this:
apiVersion: nauticus.io/v1alpha1
kind: Space
metadata:
labels:
app.kubernetes.io/name: space
app.kubernetes.io/instance: space-sample
app.kubernetes.io/part-of: nauticus
app.kubernetes.io/managed-by: kustomize
app.kubernetes.io/created-by: nauticus
name: space-sample-owners
spec:
owners:
- name: dev-team@example.com
kind: Group
kubectl apply -f config/samples/space_with_owners.yaml
Space with Resource Quota ¶
This section is dedicated to showcasing how Nauticus can be used to assign resource quotas to underlying namespaces. This feature is particularly useful for ensuring that resources are being utilized efficiently within a namespace, and can also be used to prevent overconsumption of resources.
To begin, you will need to create a new Space resource and specify the desired resource quotas within the resource definition. For example, you may want to set a limit on the number of pods that can be created within the namespace, or limit the amount of CPU and memory that can be consumed.
Here his an example of a Space with resource quota specification:
apiVersion: nauticus.io/v1alpha1
kind: Space
metadata:
labels:
app.kubernetes.io/name: space
app.kubernetes.io/instance: space-sample
app.kubernetes.io/part-of: nauticus
app.kubernetes.io/managed-by: kustomize
app.kubernetes.io/created-by: nauticus
name: space-sample-rc
spec:
resourceQuota:
hard:
limits.cpu: "8"
limits.memory: 16Gi
requests.cpu: "8"
requests.memory: 16Gi
Once you have defined the resource quotas, you can use the kubectl apply command to create the Space and apply the resource quotas to the underlying namespace.
kubectl apply -f config/samples/space_with_resource_quotas.yaml
You can also update or remove the resource quotas by updating or delete the space resource. The update will be automatically propagate to the underlying namespace.
Space with Network Policies ¶
Network policies are an important aspect of securing and isolating resources within a Kubernetes cluster. Nauticus allows you to easily create and manage network policies for your spaces.
When you create a space, you have the option to specify a enableDefaultStrictMode parameter. When set to true, Nauticus will create a default network policy that restricts ingress communication from other spaces or namespaces, except for namespaces that have the label nauticus.io/role: system. This default policy will help secure your space and prevent unauthorized access to your resources.
To create a network policy for your space, you can use the kubectl command line tool and specify the desired rules in a manifest file. Here is an example of a manifest file that creates a network policy in underlying space's namespace.
apiVersion: nauticus.io/v1alpha1
kind: Space
metadata:
labels:
app.kubernetes.io/name: space
app.kubernetes.io/instance: space-sample
app.kubernetes.io/part-of: nauticus
app.kubernetes.io/managed-by: kustomize
app.kubernetes.io/created-by: nauticus
name: space-sample-np
spec:
networkPolicies:
enableDefaultStrictMode: true # false
items:
- policyTypes:
- Ingress
- Egress
egress:
- to:
- ipBlock:
cidr: 0.0.0.0/0
except:
- 192.168.0.0/16
ingress:
- from:
- namespaceSelector:
matchLabels:
app.kubernetes.io/instance: space-all-in-one
- podSelector: { }
- ipBlock:
cidr: 192.168.0.0/16
podSelector: { }
kubectl apply -f config/samples/space_with_network_policy.yaml
Assign Additional RoleBindings ¶
One of the features of Nauticus is the ability to assign additional role bindings to a space. This allows you to grant specific roles and permissions to users or service accounts within the space.
To assign additional role bindings, you can include the additionalRoleBindings field in the space specification. This field should contain a list of objects, each with subjects and roleRef field.
apiVersion: nauticus.io/v1alpha1
kind: Space
metadata:
labels:
app.kubernetes.io/name: space
app.kubernetes.io/instance: space-sample
app.kubernetes.io/part-of: nauticus
app.kubernetes.io/managed-by: kustomize
app.kubernetes.io/created-by: nauticus
name: space-sample-add-rb
spec:
additionalRoleBindings:
- roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: viewer
subjects:
- name: Sam
kind: User
kubectl apply -f config/samples/space_with_additional_rolebindings.yaml
Assign Limit Ranges ¶
The limit range feature in Nauticus allows users to set constraints on the resources that can be requested and consumed by the containers in a namespace. This feature provides an additional layer of control over resource utilization in the cluster, ensuring that high resource-intensive workloads do not affect the performance of other services. To utilize this feature, users can specify limit ranges in their Space configuration and Nauticus will enforce these limits at runtime. This provides a simple and effective way to manage the resource consumption in a multi-tenant cluster environment.
apiVersion: nauticus.io/v1alpha1
kind: Space
metadata:
labels:
app.kubernetes.io/name: space
app.kubernetes.io/instance: space-sample
app.kubernetes.io/part-of: nauticus
app.kubernetes.io/managed-by: kustomize
app.kubernetes.io/created-by: nauticus
name: space-sample-lr
spec:
limitRanges:
items:
-
limits:
-
max:
cpu: "1"
memory: 1Gi
min:
cpu: 50m
memory: 5Mi
type: Pod
-
default:
cpu: 200m
memory: 100Mi
defaultRequest:
cpu: 100m
memory: 10Mi
max:
cpu: "1"
memory: 1Gi
min:
cpu: 50m
memory: 5Mi
type: Container
-
max:
storage: 10Gi
min:
storage: 1Gi
type: PersistentVolumeClaim
kubectl apply -f config/samples/space_with_limit_ranges.yaml
Create Space's Service Accounts ¶
Nauticus provides a convenient way to create a Kubernetes Service Account that can be used as a Cloud Provider Service Account using Cloud specific IAM Binding. Instead of manually creating the Service Account and adding the necessary annotations to bind it with the cloud-specific IAM, Nauticus allows you to simply create the Service Account with the desired annotations.
To create a Service Account using Nauticus, simply specify the desired annotations in the Space configuration file. Nauticus will then take care of creating the Service Account with the specified annotations.
For more details about Workload Identity.
apiVersion: nauticus.io/v1alpha1
kind: Space
metadata:
labels:
app.kubernetes.io/name: space
app.kubernetes.io/instance: space-sample
app.kubernetes.io/part-of: nauticus
app.kubernetes.io/managed-by: kustomize
app.kubernetes.io/created-by: nauticus
name: space-sample-sa-gcp
spec:
serviceAccounts:
items:
- name: cloudsql
annotations:
iam.gke.io/gcp-service-account: cloudsql@GSA_PROJECT.iam.gserviceaccount.com
- name: gcs
annotations:
iam.gke.io/gcp-service-account: gcs@GSA_PROJECT.iam.gserviceaccount.com
kubectl apply -f config/samples/space_with_gcp_service_accounts.yaml
For more details about Configuring a Kubernetes service account to assume an IAM role.
apiVersion: nauticus.io/v1alpha1
kind: Space
metadata:
labels:
app.kubernetes.io/name: space
app.kubernetes.io/instance: space-sample
app.kubernetes.io/part-of: nauticus
app.kubernetes.io/managed-by: kustomize
app.kubernetes.io/created-by: nauticus
name: space-sample-sa-aws
spec:
serviceAccounts:
items:
- name: rds
annotations:
eks.amazonaws.com/role-arn: arn:aws:iam::111122223333:role/rds
kubectl apply -f config/samples/space_with_aws_service_accounts.yaml
For more details about Azure Workload Identity.
apiVersion: nauticus.io/v1alpha1
kind: Space
metadata:
labels:
app.kubernetes.io/name: space
app.kubernetes.io/instance: space-sample
app.kubernetes.io/part-of: nauticus
app.kubernetes.io/managed-by: kustomize
app.kubernetes.io/created-by: nauticus
name: space-sample-sa-azure
spec:
serviceAccounts:
items:
- name: azuresql
annotations:
azure.workload.identity/tenant-id: "${APPLICATION_OR_USER_ASSIGNED_IDENTITY_TENANT_ID}"
kubectl apply -f config/samples/space_with_azure_service_accounts.yaml
Once the Space is created, Nauticus will create a Service Account with the specified annotations and assign it to the underlying Namespace. This allows the Namespace to access the necessary resources in the cloud provider, as specified by the annotations.
Space Example with All Features Combined ¶
In this example, we will demonstrate how to create a Space in Nauticus that combines all the features discussed so far: resource quota, network policy, space owners, and additional role bindings.
apiVersion: nauticus.io/v1alpha1
kind: Space
metadata:
labels:
app.kubernetes.io/name: space
app.kubernetes.io/instance: space-all-in-one
app.kubernetes.io/part-of: nauticus
app.kubernetes.io/managed-by: kustomize
app.kubernetes.io/created-by: nauticus
name: space-all-in-one
spec:
resourceQuota:
hard:
limits.cpu: "8"
limits.memory: 16Gi
requests.cpu: "8"
requests.memory: 16Gi
owners:
- name: smile
kind: User
- name: smile@group.com
kind: Group
additionalRoleBindings:
- roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: viewer
subjects:
- name: alice
kind: User
networkPolicies:
enableDefaultStrictMode: true # false
items:
- policyTypes:
- Ingress
- Egress
egress:
- to:
- ipBlock:
cidr: 0.0.0.0/0
except:
- 192.168.0.0/16
ingress:
- from:
- namespaceSelector:
matchLabels:
app.kubernetes.io/instance: space-all-in-one
- podSelector: { }
- ipBlock:
cidr: 192.168.0.0/16
podSelector: { }
limitRanges:
items:
- limits:
- max:
cpu: "1"
memory: 1Gi
min:
cpu: 50m
memory: 5Mi
type: Pod
- default:
cpu: 200m
memory: 100Mi
defaultRequest:
cpu: 100m
memory: 10Mi
max:
cpu: "1"
memory: 1Gi
min:
cpu: 50m
memory: 5Mi
type: Container
- max:
storage: 10Gi
min:
storage: 1Gi
type: PersistentVolumeClaim
serviceAccounts:
items:
- name: cloudsql
annotations:
iam.gke.io/gcp-service-account: cloudsql@GSA_PROJECT.iam.gserviceaccount.com
- name: gcs
annotations:
iam.gke.io/gcp-service-account: gcs@GSA_PROJECT.iam.gserviceaccount.com
kubectl apply -f config/samples/space_with_all.yaml
After creating the Space resource, you can verify the resource quota and network policy by checking the respective resources in the namespace created for this Space. You can also check the role bindings and owners by using the
kubectl get rolebindings,networkpolicies,resourcequotas,limitranges -n space-all-in-one
kubectl describe space space-all-in-one
This Space example demonstrates how Nauticus enables you to easily manage and control your Kubernetes resources by combining various features in a single resource.