diff --git a/manifests/modules/introduction/helm/.workshop/cleanup.sh b/manifests/modules/introduction/basics/helm/.workshop/cleanup.sh similarity index 100% rename from manifests/modules/introduction/helm/.workshop/cleanup.sh rename to manifests/modules/introduction/basics/helm/.workshop/cleanup.sh diff --git a/manifests/modules/introduction/helm/.workshop/terraform/main.tf b/manifests/modules/introduction/basics/helm/.workshop/terraform/main.tf similarity index 100% rename from manifests/modules/introduction/helm/.workshop/terraform/main.tf rename to manifests/modules/introduction/basics/helm/.workshop/terraform/main.tf diff --git a/manifests/modules/introduction/helm/.workshop/terraform/outputs.tf b/manifests/modules/introduction/basics/helm/.workshop/terraform/outputs.tf similarity index 100% rename from manifests/modules/introduction/helm/.workshop/terraform/outputs.tf rename to manifests/modules/introduction/basics/helm/.workshop/terraform/outputs.tf diff --git a/manifests/modules/introduction/helm/.workshop/terraform/vars.tf b/manifests/modules/introduction/basics/helm/.workshop/terraform/vars.tf similarity index 100% rename from manifests/modules/introduction/helm/.workshop/terraform/vars.tf rename to manifests/modules/introduction/basics/helm/.workshop/terraform/vars.tf diff --git a/manifests/modules/introduction/helm/values.yaml b/manifests/modules/introduction/basics/helm/values.yaml similarity index 100% rename from manifests/modules/introduction/helm/values.yaml rename to manifests/modules/introduction/basics/helm/values.yaml diff --git a/manifests/modules/introduction/kustomize/deployment.yaml b/manifests/modules/introduction/basics/kustomize/deployment.yaml similarity index 100% rename from manifests/modules/introduction/kustomize/deployment.yaml rename to manifests/modules/introduction/basics/kustomize/deployment.yaml diff --git a/manifests/modules/introduction/kustomize/kustomization.yaml b/manifests/modules/introduction/basics/kustomize/kustomization.yaml similarity index 72% rename from manifests/modules/introduction/kustomize/kustomization.yaml rename to manifests/modules/introduction/basics/kustomize/kustomization.yaml index 5dd2dae094..35f499f927 100644 --- a/manifests/modules/introduction/kustomize/kustomization.yaml +++ b/manifests/modules/introduction/basics/kustomize/kustomization.yaml @@ -1,6 +1,6 @@ apiVersion: kustomize.config.k8s.io/v1beta1 kind: Kustomization resources: - - ../../../base-application/checkout + - ../../../../base-application/checkout patches: - path: deployment.yaml diff --git a/website/docs/introduction/basics/access/index.md b/website/docs/introduction/basics/access/index.md new file mode 100644 index 0000000000..86219508dd --- /dev/null +++ b/website/docs/introduction/basics/access/index.md @@ -0,0 +1,12 @@ +--- +title: Cluster Access +sidebar_position: 20 +description: "Learn how to configure access and interact with Kubernetes clusters using kubeconfig and kubectl." +--- + +# Interacting with Kubernetes + +Now that you understand what Kubernetes is, let's learn **how to interact with it** using the command-line tool and cluster configuration. + +- [kubectl](./kubectl) - The command-line tool for managing Kubernetes resources and applications. +- [kubeconfig](./kubeconfig) - A `YAML` file holds the information needed to interact with Kubernetes API Server. \ No newline at end of file diff --git a/website/docs/introduction/basics/access/kubeconfig.md b/website/docs/introduction/basics/access/kubeconfig.md new file mode 100644 index 0000000000..e0bb402e39 --- /dev/null +++ b/website/docs/introduction/basics/access/kubeconfig.md @@ -0,0 +1,205 @@ +--- +title: kubeconfig +sidebar_position: 20 +description: "Learn how to configure access to Kubernetes clusters using kubeconfig and AWS EKS integration." +--- + +# Cluster Access & Configuration + +To use kubectl with a Kubernetes cluster, you need to configure access using a **kubeconfig** file. + +The kubeconfig file is a YAML configuration file that tells kubectl: +- **Where** to find your Kubernetes cluster (API server endpoint) +- **How** to authenticate with it (credentials) +- **Which** cluster and user to use by default (context) + +### kubeconfig Structure + +A kubeconfig file contains three main sections: + +```yaml +apiVersion: v1 +kind: Config +clusters: # Information about Kubernetes clusters +- name: my-cluster + cluster: + server: https://kubernetes-api-server:6443 + certificate-authority-data: + +users: # Authentication credentials for different users +- name: my-user + user: + token: + # OR client-certificate-data and client-key-data + # OR exec command for dynamic authentication + +contexts: # Combinations of cluster + user + namespace +- name: my-context + context: + cluster: my-cluster + user: my-user + namespace: default + +current-context: my-context # Which context to use by default +``` + +### Key Components Explained + +**Clusters**: Define how to connect to Kubernetes API servers +- **server**: The API server URL (e.g., `https://my-cluster.example.com:6443`) +- **certificate-authority**: CA certificate to verify the server's identity +- **insecure-skip-tls-verify**: Skip TLS verification (not recommended for production) + +**Users**: Define authentication methods +- **token**: Bearer token authentication +- **client-certificate/client-key**: Mutual TLS authentication +- **username/password**: Basic authentication (rarely used) +- **exec**: External command for dynamic authentication (like AWS CLI) + +**Contexts**: Combine cluster + user + optional default namespace +- Allows you to easily switch between different clusters or users +- Can set a default namespace to avoid specifying `-n` repeatedly + +### Managing Multiple Clusters + +kubeconfig supports multiple clusters, users, and contexts in a single file: + +```bash +# View your complete kubeconfig +$ kubectl config view + +# List all available contexts +$ kubectl config get-contexts + +# Check current context +$ kubectl config current-context +``` + +Additional commands: +``` +# Switch between contexts +$ kubectl config use-context + +# Set default namespace for current context +$ kubectl config set-context --current --namespace= +``` + +### kubeconfig File Location + +By default, kubectl looks for kubeconfig at: +- `~/.kube/config` (Linux/macOS) +- `%USERPROFILE%\.kube\config` (Windows) + +You can override this with: +- `KUBECONFIG` environment variable +- `--kubeconfig` flag with kubectl commands + +## EKS-Specific Configuration + +Amazon EKS integrates seamlessly with the standard kubeconfig pattern but adds AWS-specific authentication. + +### AWS CLI Integration + +For EKS clusters, AWS CLI provides a convenient way to configure kubectl: + +```bash +# Configure kubectl for your EKS cluster +$ aws eks update-kubeconfig --region us-west-2 --name eks-workshop + +# Verify the connection +$ kubectl get nodes +``` + +### What AWS CLI Does + +When you run `aws eks update-kubeconfig`, it: + +1. **Retrieves cluster information** from the EKS API +2. **Updates your kubeconfig file** (`~/.kube/config`) +3. **Sets up AWS authentication** using the `aws eks get-token` command + +### EKS kubeconfig Structure + +Here's what an EKS entry looks like in your kubeconfig: + +```yaml +clusters: +- cluster: + certificate-authority-data: + server: https://ABC123.gr7.us-west-2.eks.amazonaws.com + name: arn:aws:eks:us-west-2:123456789012:cluster/eks-workshop + +users: +- name: arn:aws:eks:us-west-2:123456789012:cluster/eks-workshop + user: + exec: + apiVersion: client.authentication.k8s.io/v1beta1 + command: aws + args: + - eks + - get-token + - --cluster-name + - eks-workshop + - --region + - us-west-2 + +contexts: +- context: + cluster: arn:aws:eks:us-west-2:123456789012:cluster/eks-workshop + user: arn:aws:eks:us-west-2:123456789012:cluster/eks-workshop + name: arn:aws:eks:us-west-2:123456789012:cluster/eks-workshop +``` + +### EKS Authentication Flow + +When you run kubectl commands with EKS: + +1. **kubectl** reads the kubeconfig file +2. **Executes** `aws eks get-token` command +3. **AWS CLI** uses your AWS credentials to get a temporary token +4. **kubectl** uses this token to authenticate with the EKS API server +5. **EKS** validates the token and maps it to Kubernetes RBAC permissions + +### AWS Credentials for EKS + +EKS authentication relies on your AWS credentials, which can come from: +- **AWS CLI profiles** (`~/.aws/credentials`) +- **Environment variables** (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`) +- **IAM roles** (EC2 instance profiles, EKS service accounts) +- **AWS SSO** sessions + +### Viewing Your EKS Configuration + +```bash +# See your current kubeconfig (including EKS entries) +$ kubectl config view + +# Check which EKS cluster you're connected to +$ kubectl config current-context + +# Test your connection +$ kubectl get nodes + +# Get cluster information +$ kubectl cluster-info +``` + +## Key Concepts to Remember + +### kubeconfig Fundamentals +- **kubeconfig file** is the standard way Kubernetes stores cluster connection information +- **Three main components**: clusters (where), users (who), contexts (which combination) +- **Works the same** across all Kubernetes distributions (EKS, GKE, AKS, self-managed) +- **File location**: `~/.kube/config` by default, customizable via `KUBECONFIG` environment variable + +### EKS Integration +- **AWS CLI integration** uses standard kubeconfig with AWS-specific authentication via `aws eks get-token` +- **Dynamic authentication** - tokens are generated on-demand using your AWS credentials +- **No static credentials** stored in kubeconfig - more secure than traditional approaches + +### Context Management +- **Contexts** combine cluster + user + optional namespace for easy switching +- **Multiple clusters** can be managed from a single kubeconfig file +- **Default namespace** can be set per context to avoid repetitive `-n` flags + +Now that you understand how kubectl connects to clusters, let's explore the core Kubernetes resources, starting with [Namespaces](../../namespaces) for organizing your resources, then [Pods](../../pods) - the smallest deployable units in Kubernetes. \ No newline at end of file diff --git a/website/docs/introduction/basics/access/kubectl.md b/website/docs/introduction/basics/access/kubectl.md new file mode 100644 index 0000000000..88f97a2c41 --- /dev/null +++ b/website/docs/introduction/basics/access/kubectl.md @@ -0,0 +1,139 @@ +--- +title: kubectl +sidebar_position: 10 +description: "Learn essential kubectl commands for managing Kubernetes resources." +--- + +[kubectl](https://kubernetes.io/docs/reference/kubectl/) (pronounced "kube-control" or "kube-c-t-l") is the command-line tool that communicates with the Kubernetes API server. It translates your commands into API calls and presents the results in a human-readable format. + +All kubectl commands follow this pattern: +``` +kubectl [command] [type] [name] [flags] +``` + +Examples: +- `kubectl get pods` - List all pods +- `kubectl describe service ui` - Get detailed info about the ui service +- `kubectl apply -f deployment.yaml` - Create resources from a file + +kubectl has excellent built-in documentation. Let's explore it: + +```bash +$ kubectl +kubectl controls the Kubernetes cluster manager. + + Find more information at: https://kubernetes.io/docs/reference/kubectl/ + +Basic Commands (Beginner): + create Create a resource from a file or from stdin + expose Take a replication controller, service, deployment or pod and expose it as a new +Kubernetes service + run Run a particular image on the cluster + set Set specific features on objects + +Basic Commands (Intermediate): + explain Get documentation for a resource + get Display one or many resources + edit Edit a resource on the server + delete Delete resources by file names, stdin, resources and names, or by resources and +label selector + +Deploy Commands: + rollout Manage the rollout of a resource + scale Set a new size for a deployment, replica set, or replication controller + autoscale Auto-scale a deployment, replica set, stateful set, or replication controller + +Cluster Management Commands: + certificate Modify certificate resources + cluster-info Display cluster information + top Display resource (CPU/memory) usage + cordon Mark node as unschedulable + uncordon Mark node as schedulable + drain Drain node in preparation for maintenance + taint Update the taints on one or more nodes + +Troubleshooting and Debugging Commands: + describe Show details of a specific resource or group of resources + logs Print the logs for a container in a pod + attach Attach to a running container + exec Execute a command in a container + port-forward Forward one or more local ports to a pod + proxy Run a proxy to the Kubernetes API server + cp Copy files and directories to and from containers + auth Inspect authorization + debug Create debugging sessions for troubleshooting workloads and nodes + events List events + +Advanced Commands: + diff Diff the live version against a would-be applied version + apply Apply a configuration to a resource by file name or stdin + patch Update fields of a resource + replace Replace a resource by file name or stdin + wait Experimental: Wait for a specific condition on one or many resources + kustomize Build a kustomization target from a directory or URL + +Settings Commands: + label Update the labels on a resource + annotate Update the annotations on a resource + completion Output shell completion code for the specified shell (bash, zsh, fish, or +powershell) + +Subcommands provided by plugins: + connect The command connect is a plugin installed by the user + +Other Commands: + api-resources Print the supported API resources on the server + api-versions Print the supported API versions on the server, in the form of "group/version" + config Modify kubeconfig files + plugin Provides utilities for interacting with plugins + version Print the client and server version information + +Usage: + kubectl [flags] [options] + +Use "kubectl --help" for more information about a given command. +Use "kubectl options" for a list of global command-line options (applies to all commands). +``` + +`kubectl` organizes commands into logical categories. Understanding these categories helps you find the right command for any task. +1. Basic Commands (Beginner & Intermediate) +2. Deploy Commands +3. Cluster Management Commands +4. Troubleshooting and Debugging Commands +5. Advanced Commands +6. Settings Commands +7. Other Commands + +### Getting Help +kubectl has excellent built-in help: +```bash +# See all command categories +$ kubectl --help + +# Get help for specific commands +$ kubectl get --help +$ kubectl apply --help + +# Get resource documentation +$ kubectl explain pod +$ kubectl explain deployment.spec.template +``` + +## Workshop Patterns + +Throughout this workshop, you'll frequently use these kubectl commands: + +- `kubectl apply -k` for Kustomize deployments +- `kubectl get pods -n ` for checking application status +- `kubectl describe` and `kubectl logs` for troubleshooting +- `kubectl port-forward` for accessing applications locally + +## Key Concepts to Remember + +- **Command pattern**: `kubectl [command] [type] [name] [flags]` - all commands follow this structure +- **Get help**: Use `kubectl --help` or `kubectl --help` to discover options +- **Declarative approach**: Use `kubectl apply -f` for production deployments +- **Namespace awareness**: Always specify `-n ` or use `-A` for all namespaces +- **Essential commands**: `get`, `describe`, `logs`, `apply`, `port-forward` cover most daily tasks + +Now that you understand kubectl commands, you can learn more about [how kubectl connects to clusters](../cluster-access), or jump ahead to explore the core Kubernetes resources, starting with [Namespaces](../../namespaces) for organizing your resources. \ No newline at end of file diff --git a/website/docs/introduction/basics/architecture.md b/website/docs/introduction/basics/architecture.md new file mode 100644 index 0000000000..57589520e2 --- /dev/null +++ b/website/docs/introduction/basics/architecture.md @@ -0,0 +1,71 @@ +--- +title: Architecture +sidebar_position: 10 +description: "Understand Kubernetes and Amazon EKS architecture fundamentals." +--- + +# Kubernetes Architecture + +Kubernetes follows a **control plane–worker node architecture**, where the **control plane** manages the cluster and **worker nodes** run your workloads. + +![Kubernetes Cluster Architecture](https://kubernetes.io/images/docs/kubernetes-cluster-architecture.svg) +*Figure: Simplified Kubernetes cluster architecture.* + +### Control Plane Components + +The control plane makes global decisions about the cluster and ensures the system's desired state. + +- **API Server** — Acts as the front-end for Kubernetes, exposing the Kubernetes API to users and components. +- **etcd** — A highly available key-value store that holds all cluster data. +- **Scheduler** — Assigns Pods to nodes based on resource availability and constraints. +- **Controller Manager** — Runs background processes (controllers) that maintain cluster health and reconcile actual vs. desired states. + +### Worker Node Components + +Each node runs the components needed to host and manage Pods. + +- **kubelet** — Communicates with the control plane and ensures containers are running as expected. +- **Container Runtime** — Executes containers (e.g., containerd, CRI-O). +- **kube-proxy** — Maintains network rules and manages communication between Pods and services. + +--- + +## Amazon EKS Architecture + +**Amazon Elastic Kubernetes Service (EKS)** is a managed Kubernetes service that simplifies cluster operations. +It takes care of control plane management, upgrades, and high availability, so you can focus on your workloads. + +With EKS, you can: +- **Deploy applications faster** with less operational overhead +- **Scale seamlessly** to handle changing workloads +- **Enhance security** using AWS IAM and managed updates +- **Choose your compute model** — traditional EC2 nodes or serverless with EKS Auto Mode + +### Shared Responsibility Model + +In Amazon EKS: +- **AWS manages the control plane** — including the API Server, etcd, scheduler, and controllers. +- **You manage the worker nodes** — EC2, Fargate, or hybrid options where your applications run. +- **AWS services integrate natively** — including load balancers, IAM roles, VPC networking, and storage. + +![Amazon EKS Architecture](https://docs.aws.amazon.com/images/eks/latest/userguide/images/whatis.png) +*Figure: Amazon EKS architecture and integration with AWS services.* + +## Key Design Principles + +Understanding these principles will help you work more effectively with Kubernetes: + +### Control Plane vs. Worker Nodes +- **Control plane** components (API Server, etcd, Scheduler, Controller Manager) handle cluster-wide decisions and state management +- **Worker nodes** (kubelet, container runtime, kube-proxy) focus on running and networking your applications +- This separation allows for scalable, resilient cluster operations + +### EKS Advantages +- **Reduced operational burden** — AWS manages control plane complexity, patching, and high availability +- **Native AWS integration** — Seamless connectivity with VPC, IAM, Load Balancers, and other AWS services +- **Flexible compute options** — Choose between EC2, Fargate, or Auto Mode based on your workload needs + +### Core Concepts +- **Declarative configuration** — Define desired state; Kubernetes controllers work to achieve it +- **API-driven** — All interactions go through the Kubernetes API for consistency and auditability +- **Extensible** — Custom resources and controllers allow you to extend Kubernetes functionality \ No newline at end of file diff --git a/website/docs/introduction/basics/configuration/index.md b/website/docs/introduction/basics/configuration/index.md index 207e7fa003..5c310464f8 100644 --- a/website/docs/introduction/basics/configuration/index.md +++ b/website/docs/introduction/basics/configuration/index.md @@ -1,6 +1,6 @@ --- title: Configuration -sidebar_position: 50 +sidebar_position: 60 --- # Configuration diff --git a/website/docs/introduction/basics/index.md b/website/docs/introduction/basics/index.md index 7f0d380739..a829ce2836 100644 --- a/website/docs/introduction/basics/index.md +++ b/website/docs/introduction/basics/index.md @@ -1,13 +1,13 @@ --- -title: Kubernetes Basics +title: Kubernetes Fundamentals sidebar_position: 60 sidebar_custom_props: { "module": true } -description: "Learn fundamental Kubernetes concepts including architecture, Helm, and Kustomize." +description: "Learn fundamental Kubernetes concepts, kubectl CLI, and package management tools." --- -# Kubernetes Concepts +# Kubernetes Fundamentals -Before diving into hands-on labs, it's important to understand **how Kubernetes works** and **the tools you'll use** throughout this workshop. This section introduces the core architecture, key components, and deployment tools that form the foundation of your EKS learning journey. +Kubernetes is the industry-standard platform for running containerized applications at scale. It automates deployment, scaling, and operations, letting you focus on your applications instead of infrastructure. In this lab, we’ll cover the core concepts of Kubernetes—pods, deployments, services, and more—so you can confidently build and manage cloud-native applications on Amazon EKS. :::tip Before you start Prepare your environment for this section: @@ -18,70 +18,12 @@ $ prepare-environment introduction/basics ::: -## Kubernetes Architecture Overview - -Kubernetes follows a **control plane–worker node architecture**, where the **control plane** manages the cluster and **worker nodes** run your workloads. - -![Kubernetes Cluster Architecture](https://kubernetes.io/images/docs/kubernetes-cluster-architecture.svg) -*Figure: Simplified Kubernetes cluster architecture.* - -### Control Plane Components - -The control plane makes global decisions about the cluster and ensures the system’s desired state. - -- **API Server** — Acts as the front-end for Kubernetes, exposing the Kubernetes API to users and components. -- **etcd** — A highly available key-value store that holds all cluster data. -- **Scheduler** — Assigns Pods to nodes based on resource availability and constraints. -- **Controller Manager** — Runs background processes (controllers) that maintain cluster health and reconcile actual vs. desired states. - -### Worker Node Components - -Each node runs the components needed to host and manage Pods. - -- **kubelet** — Communicates with the control plane and ensures containers are running as expected. -- **Container Runtime** — Executes containers (e.g., containerd, CRI-O). -- **kube-proxy** — Maintains network rules and manages communication between Pods and services. - ---- - -## Amazon EKS Architecture - -**Amazon Elastic Kubernetes Service (EKS)** is a managed Kubernetes service that simplifies cluster operations. -It takes care of control plane management, upgrades, and high availability, so you can focus on your workloads. - -With EKS, you can: -- **Deploy applications faster** with less operational overhead -- **Scale seamlessly** to handle changing workloads -- **Enhance security** using AWS IAM and managed updates -- **Choose your compute model** — traditional EC2 nodes or serverless with EKS Auto Mode - -### Shared Responsibility Model - -In Amazon EKS: -- **AWS manages the control plane** — including the API Server, etcd, scheduler, and controllers. -- **You manage the worker nodes** — EC2, Fargate, or hybrid options where your applications run. -- **AWS services integrate natively** — including load balancers, IAM roles, VPC networking, and storage. - -![Amazon EKS Architecture](https://docs.aws.amazon.com/images/eks/latest/userguide/images/whatis.png) -*Figure: Amazon EKS architecture and integration with AWS services.* - -## Key Points to Remember - -Understanding Kubernetes architecture is crucial for effective cluster management and troubleshooting: - -### Control Plane vs. Worker Nodes -- **Control plane** components (API Server, etcd, Scheduler, Controller Manager) handle cluster-wide decisions and state management -- **Worker nodes** (kubelet, container runtime, kube-proxy) focus on running and networking your applications -- This separation allows for scalable, resilient cluster operations - -### EKS Advantages -- **Reduced operational burden** — AWS manages control plane complexity, patching, and high availability -- **Native AWS integration** — Seamless connectivity with VPC, IAM, Load Balancers, and other AWS services -- **Flexible compute options** — Choose between EC2, Fargate, or Auto Mode based on your workload needs - -### Design Principles -- **Declarative configuration** — Define desired state; Kubernetes controllers work to achieve it -- **API-driven** — All interactions go through the Kubernetes API for consistency and auditability -- **Extensible** — Custom resources and controllers allow you to extend Kubernetes functionality - -These architectural concepts will be essential as you progress through deploying applications, managing configurations with Helm and Kustomize, and implementing advanced cluster features. +You'll be learning the following fundamental concepts in this lab: +- **[Architecture](./architecture)** - Understand how Kubernetes and Amazon EKS work under the hood +- **[Cluster Access](./access)** - Configure access and interact with clusters using kubectl and kubeconfig +- **[Namespaces](./namespaces)** - Organize and isolate resources +- **[Pods](./pods)** - The smallest deployable units in Kubernetes +- **[Workload Management](./workload-management)** - Deployments, StatefulSets, DaemonSets, and Jobs +- **[Services](./services)** - Enable network access and service discovery +- **[Configuration](./configuration)** - ConfigMaps and Secrets for application settings +- **[Package Management](./package-management)** - Kustomize and Helm for managing application \ No newline at end of file diff --git a/website/docs/introduction/basics/namespaces/index.md b/website/docs/introduction/basics/namespaces/index.md index a8e05fa3f1..425bcf0271 100644 --- a/website/docs/introduction/basics/namespaces/index.md +++ b/website/docs/introduction/basics/namespaces/index.md @@ -1,6 +1,6 @@ --- title: Namespaces -sidebar_position: 10 +sidebar_position: 20 --- # Namespaces diff --git a/website/docs/introduction/helm/index.md b/website/docs/introduction/basics/package-management/helm/index.md similarity index 59% rename from website/docs/introduction/helm/index.md rename to website/docs/introduction/basics/package-management/helm/index.md index 55f1550854..ae19c76431 100644 --- a/website/docs/introduction/helm/index.md +++ b/website/docs/introduction/basics/package-management/helm/index.md @@ -1,29 +1,40 @@ --- title: Helm -sidebar_custom_props: { "module": true } -sidebar_position: 80 +sidebar_position: 20 +description: "Learn Kubernetes package management and templating with Helm charts." --- -::required-time +# Helm -:::tip Before you start -Prepare your environment for this section: +[Helm](https://helm.sh) is a package manager for Kubernetes that helps you define, install, and upgrade Kubernetes applications. It uses a packaging format called charts, which contain all the necessary Kubernetes resource definitions to run an application. Helm simplifies the deployment and management of applications on Kubernetes clusters. -```bash timeout=600 wait=10 -$ prepare-environment introduction/helm -``` +While Kustomize excels at declarative configuration management, Helm takes a different approach focused on **templating** and **package management**. Helm is particularly valuable when you need to: -::: +- **Share applications** across teams and organizations +- **Handle complex configurations** with conditional logic +- **Manage application lifecycles** (install, upgrade, rollback) +- **Leverage existing ecosystem** of pre-built charts -Although we will primarily be interacting with Kustomize in this workshop, there will be situations where Helm will be used to install certain packages in the EKS cluster. In this lab we give a brief introduction to Helm, and we'll demonstrate how to use it to install a pre-packaged application. +## Core Concepts -:::info +### Charts +Helm uses a packaging format called charts. A chart is a collection of files that describe a related set of Kubernetes resources. A single chart might be used to deploy something simple, like a memcached pod, or something complex, like a full web app stack with HTTP servers, databases, caches, and so on. -This lab does not cover the authoring of Helm charts for your own workloads. For more information on this topic see this [guide](https://helm.sh/docs/chart_template_guide/). +A Helm package containing: +- `Chart.yaml` - metadata about the chart +- `values.yaml` - default configuration values +- `templates/` - Kubernetes manifest templates +- Optional dependencies and documentation -::: +### Releases +A **release** is an instance of a chart running in a Kubernetes cluster. You can install the same chart multiple times with different configurations. -[Helm](https://helm.sh) is a package manager for Kubernetes that helps you define, install, and upgrade Kubernetes applications. It uses a packaging format called charts, which contain all the necessary Kubernetes resource definitions to run an application. Helm simplifies the deployment and management of applications on Kubernetes clusters. +### Values +**Values** are the configuration parameters that customize how a chart behaves when installed. + +:::info +This lab focuses on using Helm charts rather than authoring them. For chart development, see the [official guide](https://helm.sh/docs/chart_template_guide/). +::: ## Helm CLI @@ -91,7 +102,7 @@ There are two common ways to provide values to charts during installation: Let's combine these methods to update our UI release. We'll use this `values.yaml` file: ```file -manifests/modules/introduction/helm/values.yaml +manifests/modules/introduction/basics/helm/values.yaml ``` This adds several custom Kubernetes annotations to the Pods, as well as overriding the UI theme. @@ -110,7 +121,7 @@ $ helm upgrade ui \ --version 1.2.1 \ --create-namespace --namespace ui \ --set replicaCount=3 \ - --values ~/environment/eks-workshop/modules/introduction/helm/values.yaml \ + --values ~/environment/eks-workshop/modules/introduction/basics/helm/values.yaml \ --wait ``` @@ -161,113 +172,25 @@ $ helm uninstall ui --namespace ui --wait This will delete all the resources created by the chart for that release from our EKS cluster. -## Deploying Applications with Helm - -Now let's see how Helm can be used to deploy our retail store application. While the workshop primarily uses Kustomize, understanding Helm is valuable as many third-party applications are distributed as Helm charts. - -### Creating a Simple Chart for the Catalog Service - -Let's create a basic Helm chart for our catalog service to understand how applications can be packaged and deployed with Helm: - -```bash -$ helm create retail-catalog -``` - -This creates a basic chart structure. Let's examine what was created: - -```bash -$ ls -la retail-catalog/ -total 8 -drwxr-xr-x 4 user user 128 Nov 15 10:30 . -drwxr-xr-x 3 user user 96 Nov 15 10:30 .. --rw-r--r-- 1 user user 1141 Nov 15 10:30 Chart.yaml -drwxr-xr-x 2 user user 64 Nov 15 10:30 charts -drwxr-xr-x 3 user user 96 Nov 15 10:30 templates --rw-r--r-- 1 user user 1862 Nov 15 10:30 values.yaml -``` - -### Customizing the Chart - -Let's modify the default values to deploy our catalog service. Update the `values.yaml` file: - -```bash -$ cat > retail-catalog/values.yaml << 'EOF' -replicaCount: 2 - -image: - repository: public.ecr.aws/aws-containers/retail-store-sample-catalog - tag: "0.4.0" - pullPolicy: IfNotPresent - -service: - type: ClusterIP - port: 80 - targetPort: 8080 - -resources: - requests: - cpu: 128m - memory: 512Mi - limits: - cpu: 256m - memory: 512Mi - -nameOverride: "catalog" -fullnameOverride: "catalog" -EOF -``` - -### Installing the Chart - -Now let's install our catalog service using the Helm chart: - -```bash -$ helm install catalog ./retail-catalog --namespace catalog --create-namespace -``` - -Verify the deployment: - -```bash -$ helm list -n catalog -NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION -catalog catalog 1 2024-11-15 10:35:42.123456789 +0000 UTC deployed retail-catalog-0.1.0 1.16.0 -``` - -Check the running pods: - -```bash -$ kubectl get pods -n catalog -NAME READY STATUS RESTARTS AGE -catalog-7d4b8c9f8d-abc12 1/1 Running 0 2m -catalog-7d4b8c9f8d-def34 1/1 Running 0 2m -``` - -### Upgrading the Release - -One of Helm's strengths is managing application upgrades. Let's scale our application by updating the replica count: - -```bash -$ helm upgrade catalog ./retail-catalog \ - --namespace catalog \ - --set replicaCount=3 -``` - -### Rolling Back - -If something goes wrong, Helm makes it easy to rollback: +## When to Use Helm -```bash -$ helm rollback catalog 1 -n catalog -``` +**Helm is ideal when:** +- You need complex templating and conditional logic +- You're distributing applications to multiple teams +- You want sophisticated release management +- You're leveraging existing charts from the ecosystem +- You need to support many different configuration scenarios -### Cleaning Up +## Key Takeaways -Remove the Helm release: +- **Templating power**: Helm's Go templates enable complex, conditional configurations +- **Release management**: Built-in support for upgrades, rollbacks, and release history +- **Package ecosystem**: Large repository of pre-built charts for common applications +- **Values-driven**: Configuration through structured values files and command-line overrides +- **Lifecycle management**: Complete application lifecycle from install to uninstall -```bash -$ helm uninstall catalog -n catalog -``` +Helm provides a powerful templating and package management solution for Kubernetes applications. It's particularly valuable when you need to distribute applications widely or handle complex configuration scenarios. -This example shows how Helm provides a higher-level abstraction for deploying applications, with built-in support for upgrades, rollbacks, and configuration management. +Both Helm and Kustomize have their place in the Kubernetes ecosystem, and many teams use both tools for different use cases. Understanding both approaches will help you choose the right tool for each situation. -Now that you understand how Helm works, you can proceed to [Kustomize](../kustomize) to learn about declarative configuration management, or jump ahead to the [Fundamentals module](/docs/fundamentals). +Next, you can explore the [Fundamentals module](/docs/fundamentals) to dive deeper into EKS-specific concepts and advanced Kubernetes patterns. \ No newline at end of file diff --git a/website/docs/introduction/helm/tests/hook-install.sh b/website/docs/introduction/basics/package-management/helm/tests/hook-install.sh similarity index 100% rename from website/docs/introduction/helm/tests/hook-install.sh rename to website/docs/introduction/basics/package-management/helm/tests/hook-install.sh diff --git a/website/docs/introduction/helm/tests/hook-replicas.sh b/website/docs/introduction/basics/package-management/helm/tests/hook-replicas.sh similarity index 100% rename from website/docs/introduction/helm/tests/hook-replicas.sh rename to website/docs/introduction/basics/package-management/helm/tests/hook-replicas.sh diff --git a/website/docs/introduction/helm/tests/hook-suite.sh b/website/docs/introduction/basics/package-management/helm/tests/hook-suite.sh similarity index 100% rename from website/docs/introduction/helm/tests/hook-suite.sh rename to website/docs/introduction/basics/package-management/helm/tests/hook-suite.sh diff --git a/website/docs/introduction/basics/package-management/index.md b/website/docs/introduction/basics/package-management/index.md new file mode 100644 index 0000000000..479df50449 --- /dev/null +++ b/website/docs/introduction/basics/package-management/index.md @@ -0,0 +1,60 @@ +--- +title: Package Management +sidebar_position: 70 +description: "Learn about Kubernetes package management and deployment tools - Kustomize and Helm." +--- + +# Package Management + +As Kubernetes applications grow in complexity, managing multiple YAML files across different environments becomes challenging. **Package management tools** help you organize, customize, and deploy applications more efficiently. + +Kubernetes offers two primary approaches to solve these challenges: + +## Kustomize - Configuration Management +**Kustomize** uses a patch-based approach to customize Kubernetes YAML files: + +- **Template-free**: Works with standard Kubernetes YAML +- **Overlay-based**: Apply patches to base configurations +- **Built into kubectl**: Native integration with `kubectl apply -k` +- **GitOps friendly**: Excellent for declarative workflows + +**Best for**: Teams preferring pure YAML, simple customizations, and GitOps workflows. + +## Helm - Package Manager +**Helm** uses templates to generate Kubernetes manifests: + +- **Templating**: Go templates with variables and functions +- **Packaging**: Bundle applications into reusable charts +- **Release management**: Install, upgrade, and rollback applications +- **Large ecosystem**: Thousands of pre-built charts available + +**Best for**: Complex applications, sharing across teams, and leveraging existing charts. + +## Comparison + +| Feature | Kustomize | Helm | +|---------|-----------|------| +| **Approach** | Patch-based | Template-based | +| **Learning Curve** | Gentler (standard YAML) | Steeper (template syntax) | +| **Release Management** | Basic (via kubectl) | Advanced (install/upgrade/rollback) | +| **Ecosystem** | Growing adoption | Mature with large chart library | +| **GitOps** | Excellent | Good (with additional tools) | + +## When to Use Which? + +**Choose Kustomize when:** +- You prefer standard Kubernetes YAML +- Your customization needs are straightforward +- You want tight kubectl integration + +**Choose Helm when:** +- You need complex templating and conditional logic +- You're distributing applications across teams +- You want sophisticated release management + +Many teams use both tools together - Helm for complex third-party applications and Kustomize for simple internal services. + +## Explore Package Management + +- **[Kustomize](./kustomize)** - Learn patch-based configuration management +- **[Helm](./helm)** - Master template-based package management \ No newline at end of file diff --git a/website/docs/introduction/kustomize/index.md b/website/docs/introduction/basics/package-management/kustomize/index.md similarity index 50% rename from website/docs/introduction/kustomize/index.md rename to website/docs/introduction/basics/package-management/kustomize/index.md index 28a17b1012..c4e47d1191 100644 --- a/website/docs/introduction/kustomize/index.md +++ b/website/docs/introduction/basics/package-management/kustomize/index.md @@ -1,72 +1,26 @@ --- title: Kustomize -sidebar_custom_props: { "module": true } -sidebar_position: 70 +sidebar_position: 10 +description: "Learn declarative configuration management with Kustomize for Kubernetes applications." --- -::required-time - -:::tip Before you start -Prepare your environment for this section: - -```bash timeout=300 wait=10 -$ prepare-environment -``` - -::: +# Kustomize [Kustomize](https://kustomize.io/) allows you to manage Kubernetes manifest files using declarative "kustomization" files. It provides the ability to express "base" manifests for your Kubernetes resources and then apply changes using composition, customization and easily making cross-cutting changes across many resources. -## Deploying the Retail Store Application - -Let's start by deploying the complete retail store application using Kustomize. The application consists of multiple microservices that work together: - -### Deploy the Base Application - -First, let's deploy the entire retail store application using the base configuration: - -```bash -$ kubectl apply -k ~/environment/eks-workshop/base-application -``` +**Key Benefits:** +- **Template-free**: Works with standard Kubernetes YAML +- **Declarative**: Define what you want, not how to get there +- **Composable**: Build complex configurations from simple pieces +- **Built-in**: Native integration with kubectl (`kubectl apply -k`) -This single command deploys all the microservices. Let's see what was created: - -```bash -$ kubectl get pods -A -l app.kubernetes.io/created-by=eks-workshop -NAME READY STATUS RESTARTS AGE -cart-6d4f8c9b8d-xyz12 1/1 Running 0 2m -catalog-7b5c9d8e9f-abc34 1/1 Running 0 2m -checkout-8c6d0e1f2g-def56 1/1 Running 0 2m -orders-9d7e2f3g4h-ghi78 1/1 Running 0 2m -ui-0e8f3g4h5i-jkl90 1/1 Running 0 2m -``` - -### Understanding the Kustomization Structure - -The base application uses a `kustomization.yaml` file that references all the component directories: - -```bash -$ cat ~/environment/eks-workshop/base-application/kustomization.yaml -``` - -Each service has its own directory with Kubernetes manifests: - -```bash -$ ls ~/environment/eks-workshop/base-application/ -cart/ catalog/ checkout/ orders/ ui/ kustomization.yaml -``` - -### Customizing with Overlays - -Now let's see Kustomize's power by creating customizations. For example, let's scale the `checkout` service horizontally by updating the `replicas` field from 1 to 3. - -Take a look at the following manifest file for the `checkout` Deployment: +For example, take a look at the following manifest file for the `checkout` Deployment: ```file manifests/base-application/checkout/deployment.yaml ``` -Rather than manually updating this YAML file, we'll use Kustomize to update the `spec/replicas` field from 1 to 3. +let's say we wanted to scale this component horizontally by updating the `replicas` field using Kustomize. Rather than manually updating this YAML file, we'll use Kustomize to update the `spec/replicas` field from 1 to 3. To do so, we'll apply the following kustomization. @@ -75,20 +29,20 @@ To do so, we'll apply the following kustomization. - Finally, the third tab shows just the diff of what has changed ```kustomization -modules/introduction/kustomize/deployment.yaml +modules/introduction/basics/kustomize/deployment.yaml Deployment/checkout ``` You can generate the final Kubernetes YAML that applies this kustomization with the `kubectl kustomize` command, which invokes `kustomize` that is bundled with the `kubectl` CLI: ```bash -$ kubectl kustomize ~/environment/eks-workshop/modules/introduction/kustomize +$ kubectl kustomize ~/environment/eks-workshop/modules/introduction/basics/kustomize ``` This will generate a lot of YAML files, which represents the final manifests you can apply directly to Kubernetes. Let's demonstrate this by piping the output from `kustomize` directly to `kubectl apply`: ```bash -$ kubectl kustomize ~/environment/eks-workshop/modules/introduction/kustomize | kubectl apply -f - +$ kubectl kustomize ~/environment/eks-workshop/modules/introduction/basics/kustomize | kubectl apply -f - namespace/checkout unchanged serviceaccount/checkout unchanged configmap/checkout unchanged @@ -101,7 +55,7 @@ deployment.apps/checkout-redis unchanged You'll notice that a number of different `checkout`-related resources are "unchanged", with the `deployment.apps/checkout` being "configured". This is intentional — we only want to apply changes to the `checkout` deployment. This happens because running the previous command actually applied two files: the Kustomize `deployment.yaml` that we saw above, as well as the following `kustomization.yaml` file which matches all files in the `~/environment/eks-workshop/base-application/checkout` folder. The `patches` field specifies the specific file to be patched: ```file -manifests/modules/introduction/kustomize/kustomization.yaml +manifests/modules/introduction/basics/kustomize/kustomization.yaml ``` To check that the number of replicas has been updated, run the following command: @@ -119,7 +73,7 @@ Instead of using the combination of `kubectl kustomize` and `kubectl apply` we c Let's try that: ```bash -$ kubectl apply -k ~/environment/eks-workshop/modules/introduction/kustomize +$ kubectl apply -k ~/environment/eks-workshop/modules/introduction/basics/kustomize ``` To reset the application manifests back to their initial state, you can simply apply the original set of manifests: @@ -137,47 +91,23 @@ $ kubectl kustomize ~/environment/eks-workshop/base-application \ This uses `envsubst` to substitute environment variable placeholders in the Kubernetes manifest files with the actual values based on your particular environment. For example in some manifests we need to reference the EKS cluster name with `$EKS_CLUSTER_NAME` or the AWS region with `$AWS_REGION`. -## Advanced Kustomize Patterns - -### Environment-Specific Configurations - -Kustomize excels at managing different configurations for different environments. You might have: - -- **Base**: Common configuration shared across all environments -- **Development Overlay**: Lower resource limits, debug logging enabled -- **Production Overlay**: Higher resource limits, multiple replicas, monitoring enabled - -### Cross-Cutting Changes - -One of Kustomize's strengths is making changes across multiple resources. For example, you could: +## When to Use Kustomize -- Add labels to all resources: `commonLabels` -- Add annotations to all resources: `commonAnnotations` -- Set resource limits across all deployments -- Configure image pull policies consistently +**Kustomize is ideal when:** +- You prefer working with standard Kubernetes YAML +- You need simple to moderate customization +- You want GitOps-friendly configurations +- You're building internal applications with known requirements +- You want to avoid templating complexity -### Deploying Individual Services - -You can also deploy individual services using their specific kustomization: - -```bash -# Deploy just the catalog service -$ kubectl apply -k ~/environment/eks-workshop/base-application/catalog - -# Deploy just the UI service -$ kubectl apply -k ~/environment/eks-workshop/base-application/ui -``` - -### Viewing Generated Manifests - -Before applying changes, you can preview what Kustomize will generate: - -```bash -$ kubectl kustomize ~/environment/eks-workshop/base-application/catalog -``` +## Key Takeaways -This shows you exactly what Kubernetes resources will be created without actually applying them to the cluster. +- **Declarative approach**: Define desired state, let Kustomize handle the details +- **Composition over inheritance**: Build complex configurations from simple pieces +- **No templating required**: Work with standard Kubernetes YAML +- **Built-in kubectl support**: Native integration with `kubectl apply -k` +- **GitOps friendly**: All configurations are version-controlled YAML files -Now that you understand how Kustomize works, you can proceed to the [Getting Started](/docs/introduction/getting-started) hands-on lab or go directly to the [Fundamentals module](/docs/fundamentals). +Kustomize provides a clean, declarative way to manage Kubernetes configurations without the complexity of templating. It's particularly effective for teams that prefer to work with standard Kubernetes YAML and need straightforward customization capabilities. -To learn more about Kustomize, you can refer to the official Kubernetes [documentation](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/). +To learn more about Kustomize, you can refer to the official Kubernetes [documentation](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/). \ No newline at end of file diff --git a/website/docs/introduction/basics/pods/index.md b/website/docs/introduction/basics/pods/index.md index 7153a887c2..7b23b76934 100644 --- a/website/docs/introduction/basics/pods/index.md +++ b/website/docs/introduction/basics/pods/index.md @@ -1,6 +1,6 @@ --- title: Pods -sidebar_position: 20 +sidebar_position: 30 --- # Pods diff --git a/website/docs/introduction/basics/services/index.md b/website/docs/introduction/basics/services/index.md index a289130009..3e41d3993e 100644 --- a/website/docs/introduction/basics/services/index.md +++ b/website/docs/introduction/basics/services/index.md @@ -1,6 +1,6 @@ --- title: Services -sidebar_position: 40 +sidebar_position: 50 --- # Services diff --git a/website/docs/introduction/basics/workload-management/index.md b/website/docs/introduction/basics/workload-management/index.md index 75b9e604f2..da890af70d 100644 --- a/website/docs/introduction/basics/workload-management/index.md +++ b/website/docs/introduction/basics/workload-management/index.md @@ -1,6 +1,6 @@ --- title: Workload Management -sidebar_position: 30 +sidebar_position: 40 --- # Workload Management diff --git a/website/test-durations.json b/website/test-durations.json index 7c96f8eef5..757ecf8d64 100644 --- a/website/test-durations.json +++ b/website/test-durations.json @@ -119,24 +119,28 @@ "/fundamentals/workloads/keda/install-keda.md": 37918, "/fundamentals/workloads/keda/test-keda.md": 94797, "/fundamentals/workloads/keda/validate-ingress.md": 103610, - "/introduction/basics/configuration/configmaps/index.md": 25044, - "/introduction/basics/configuration/index.md": 1, - "/introduction/basics/configuration/secrets/index.md": 9419, - "/introduction/basics/index.md": 87253, - "/introduction/basics/namespaces/index.md": 11632, - "/introduction/basics/pods/index.md": 22068, - "/introduction/basics/services/index.md": 61307, - "/introduction/basics/workload-management/daemonsets.md": 2563, - "/introduction/basics/workload-management/deployments.md": 13833, - "/introduction/basics/workload-management/index.md": 1, - "/introduction/basics/workload-management/jobs.md": 33585, - "/introduction/basics/workload-management/statefulsets.md": 8602, "/introduction/getting-started/finish.md": 17926, "/introduction/getting-started/first.md": 12371, "/introduction/getting-started/index.md": 832, - "/introduction/helm/index.md": 182112, + "/introduction/basics/index.md": 99061, + "/introduction/basics/access/index.md": 1, + "/introduction/basics/access/kubectl.md": 80, + "/introduction/basics/access/kubeconfig.md": 1183, + "/introduction/basics/namespaces/index.md": 12875, + "/introduction/basics/pods/index.md": 24964, + "/introduction/basics/workload-management/index.md": 1, + "/introduction/basics/workload-management/deployments.md": 14198, + "/introduction/basics/workload-management/statefulsets.md": 9980, + "/introduction/basics/workload-management/daemonsets.md": 2824, + "/introduction/basics/workload-management/jobs.md": 58839, + "/introduction/basics/services/index.md": 65391, + "/introduction/basics/configuration/index.md": 1, + "/introduction/basics/configuration/configmaps/index.md": 11993, + "/introduction/basics/configuration/secrets/index.md": 11806, + "/introduction/basics/package-management/index.md": 12048, + "/introduction/basics/kustomize/index.md": 53626, + "/introduction/basics/helm/index.md": 72437, "/introduction/index.md": 1, - "/introduction/kustomize/index.md": 155526, "/networking/index.md": 1, "/networking/vpc-cni/custom-networking/configure-vpc-cni.md": 153572, "/networking/vpc-cni/custom-networking/deploy-sample-application.md": 26497, @@ -250,4 +254,4 @@ "/troubleshooting/dns/index.md": 16049, "/troubleshooting/pod/index.md": 16049, "/troubleshooting/workernodes/index.md": 16049 -} +} \ No newline at end of file