Study guide

2.3 Kubernetes API, Declarative Management & kubectl

Kubernetes and Cloud Native Associate KCNA

Track your progress as you read

Finished sections get a check mark.

1 Chapter 1: Introduction & Exam Overview

1.1 About the KCNA Exam & Certification Path 1.2 How to Use This Study Guide

2 Chapter 2: Kubernetes Fundamentals - Cluster Architecture & the API

2.1 Kubernetes Architecture & Control Plane Components 2.2 Worker Node Architecture & Node Components 2.3 Kubernetes API, Declarative Management & kubectl 2.4 Kubernetes Releases, API Versioning & Deprecation Policy

3 Chapter 3: Kubernetes Fundamentals - Workloads & Configuration

3.1 Core Workload Objects (Pods, Deployments & ReplicaSets) 3.2 Advanced Controllers (StatefulSets, DaemonSets, Jobs & CronJobs) 3.3 Namespaces, Labels, Selectors & Annotations 3.4 ConfigMaps, Secrets & Application Configuration 3.5 Pod & Container Lifecycle, Restart Policies & Graceful Termination

4 Chapter 4: Kubernetes Fundamentals - Scheduling & Autoscaling

4.1 Scheduling, Resource Management & Node Selection 4.2 Advanced Scheduling: Affinity, Topology Spread, Priority & Disruption Budgets 4.3 Autoscaling Workloads & Clusters (HPA, VPA, Cluster Autoscaler, KEDA)

5 Chapter 5: Kubernetes Fundamentals - Cluster Administration & Extensibility

5.1 Kubernetes Distributions, Installation Tools & Managed Services 5.2 Cluster Administration: Node Maintenance, Upgrades & etcd Backup 5.3 Extending Kubernetes: CRDs, Operators & the Controller Pattern

6 Chapter 6: Kubernetes Fundamentals - Containerization

6.1 Container Fundamentals, Runtimes & Registries 6.2 Container Image Anatomy: Layers, Tags, Digests & Pull Policy

7 Chapter 7: Container Orchestration - Networking & Service Discovery

7.1 Kubernetes Networking, Services & Ingress 7.2 Cluster DNS & Service Discovery with CoreDNS 7.3 NetworkPolicies, Zero-Trust Segmentation & the Gateway API

8 Chapter 8: Container Orchestration - Storage

8.1 Storage Concepts (PVs, PVCs, StorageClasses & CSI) 8.2 Volume Types, Snapshots & Stateful Storage Operations

9 Chapter 9: Container Orchestration - Security

9.1 Kubernetes Security & Access Control (RBAC & ServiceAccounts) 9.2 The 4C's of Cloud Native Security & Supply-Chain Trust 9.3 Service Mesh, mTLS & Zero-Trust Service Identity

10 Chapter 10: Container Orchestration - Troubleshooting

10.1 Container Troubleshooting & Health Probes 10.2 Cluster & Node-Level Troubleshooting

11 Chapter 11: Cloud Native Application Delivery

11.1 Cloud Native CI/CD Pipelines & Build Tooling 11.2 GitOps & Package Management (Helm, Kustomize, Argo CD & Flux) 11.3 Deployment Strategies & Release Management 11.4 Progressive Delivery Automation: Argo Rollouts, Flagger & Feature Flags 11.5 Application Debugging & Developer Workflows in Kubernetes 11.6 Platform Engineering & Developer Self-Service

12 Chapter 12: Cloud Native Architecture - Observability & Principles

12.1 Cloud Native Observability (Logging, Metrics & Tracing) 12.2 Cloud Native Principles & Architecture Patterns 12.3 Serverless, FaaS & Event-Driven Architecture

13 Chapter 13: Cloud Native Architecture - CNCF Ecosystem & Community

13.1 The CNCF Landscape, Governance & Project Lifecycle 13.2 Cloud Native Community, Collaboration & Contribution

2.3 Kubernetes API, Declarative Management & kubectl

Key Takeaways Explain This Topic AI

Kubernetes API objects are organized by Group, Version, and Kind (GVK), forming a RESTful URL structure for versioned resource operations.

Declarative management via kubectl apply defines desired state in YAML/JSON manifests, applying changes using a three-way strategic merge.

Every Kubernetes object manifest requires four root fields: apiVersion, kind, metadata, and spec (along with system-managed status).

A kubeconfig file organizes cluster access by combining clusters, users, and contexts to define target environments.

Essential kubectl CLI commands (get, describe, logs, exec, explain) provide real-time cluster inspection, resource management, and troubleshooting.

Last updated: August 2026

2.3 Kubernetes API, Declarative Management & kubectl

All interactions with a Kubernetes cluster—whether issued by human operators via kubectl , automated CI/CD pipelines, or internal controllers—are processed as HTTP REST API calls targeting kube-apiserver . Understanding the API hierarchy, resource management paradigms, object manifests, and CLI toolsets is essential for cloud-native operations.

1. RESTful API Structure & GVK Paradigm

The Kubernetes API is structured logically around the Group / Version / Kind (GVK) model. This schema hierarchy categorizes resources and manages API lifecycle evolution. KUBERNETES REST API SCHEME

  • |
  • +-------------------------+-------------------------+
  • | |
  • Core API Group (/api/v1) Named API Groups (/apis/GROUP/VERSION)
  • e.g., Pods, Services, ConfigMaps e.g., apps/v1, networking.k8s.io/v1
  • Group, Version, Kind Breakdown

API Group : A collection of related resource types. The Core Group (legacy group) is served under /api/v1 (e.g., Pod , Service , Namespace , ConfigMap , Node ). Named Groups are served under /apis/GROUP/VERSION (e.g., apps , batch , networking.k8s.io , rbac.authorization.k8s.io ).

API Version : Indicates maturity and stability:

v1alpha1 : Experimental features; subject to breaking schema changes without notice.

v1beta1 : Feature-complete; enabled by default but may be deprecated in future releases.

v1 : Stable; guaranteed backward compatibility across major release cycles.

Kind : The specific object schema name defined in code (e.g., Deployment , StatefulSet , Service , CustomResourceDefinition ).

GVK vs. GVR: While GVK (Group/Version/Kind) refers to the schema definition used in manifest code, GVR (Group/Version/Resource) refers to the corresponding HTTP REST endpoint path exposed by the API server (e.g., /apis/apps/v1/namespaces/default/deployments ).

2. Imperative vs. Declarative Management

Kubernetes supports three distinct approaches for managing cluster objects:

  • A. Imperative Commands ( kubectl run , kubectl create )
  • Directly command Kubernetes on how to perform an operational step: # Create a deployment imperatively
  • kubectl create deployment web-server --image=nginx:1.25 --replicas=3
  • # Expose the deployment as a ClusterIP service
  • kubectl expose deployment web-server --port=80 --target-port=80

Pros : Fast, convenient for ad-hoc testing and emergency troubleshooting.

Cons : Lacks auditability, cannot be reviewed in version control, hard to reproduce.

B. Imperative Object Configuration ( kubectl create -f )

Operate on specific manifest files with explicit verbs ( create , replace , delete ). While files are used, the user explicitly dictates the action to perform.

C. Declarative Object Configuration ( kubectl apply -f )

Specify the desired state in YAML/JSON manifests and instruct Kubernetes to reconcile current state toward desired state using kubectl apply : # Declaratively apply all manifests in a directory

  • kubectl apply -f ./manifests/
  • The Three-Way Strategic Merge

When kubectl apply is executed, Kubernetes compares three states:

The local manifest file provided by the user.

The live object configuration currently running in the cluster.

The last-applied-configuration annotation stored on the live object ( kubectl.kubernetes.io/last-applied-configuration ).

This three-way merge ensures that changes made out-of-band by controllers (such as horizontal pod autoscalers updating replica counts) are preserved while applying user updates.

  • 3. Anatomy of a YAML Object Manifest
  • Every Kubernetes YAML resource definition requires four top-level root keys: apiVersion: apps/v1
  • kind: Deployment

metadata:

  • name: web-app-deployment
  • namespace: production

labels:

  • app: web-app
  • environment: production

spec:

replicas: 3

selector:

matchLabels:

app: web-app

template:

metadata:

labels:

app: web-app

spec:

containers:

  • name: nginx-container
  • image: nginx:1.25.3

ports:

- containerPort: 80

resources:

requests:

  • cpu: "100m"
  • memory: "128Mi"

limits:

  • cpu: "500m"
  • memory: "512Mi"
  • Root Field Definitions

apiVersion : The API Group and Version schema matching the resource (e.g., apps/v1 ).

kind : The object type to create (e.g., Deployment ).

metadata : Unique identification data including name , namespace , labels (key-value metadata for filtering), and annotations (non-identifying operational data).

spec : The desired state specification defining container images, replicas, ports, and volumes.

status : System-managed field populated by control plane controllers representing actual live state.

4. Kubeconfig File Structure

kubectl uses a configuration file known as kubeconfig (default location: ~/.kube/config ) to locate and authenticate against cluster API endpoints.

Kubeconfig Architecture

A kubeconfig file contains three main array sections:

clusters : Server URLs and Certificate Authority ( certificate-authority-data ) details.

users : Authentication credentials (client certificates, bearer tokens, or IAM plugins).

  • contexts : Binds a specific cluster , user , and default namespace into an environment target. apiVersion: v1
  • kind: Config
  • current-context: dev-context

clusters:

- name: dev-cluster

cluster:

server: https://192.168.1.100:6443

certificate-authority-data: LS0tLS1CRUdJTi...

users:

- name: dev-user

user:

client-certificate-data: LS0tLS1CRUdJTi...

client-key-data: LS0tLS1CRUdJTi...

contexts:

- name: dev-context

context:

  • cluster: dev-cluster
  • user: dev-user
  • namespace: development
  • Practical Kubeconfig Commands # Display formatted kubeconfig settings
  • kubectl config view
  • # List all available contexts
  • kubectl config get-contexts
  • # Switch active context to target cluster
  • kubectl config use-context dev-context
  • # Change default namespace for current context
  • kubectl config set-context --current --namespace=production
  • 5. Essential kubectl Commands

Command Usage Example Operational Purpose

kubectl get kubectl get pods -n production -o wide List resources with output formatting ( -o json , -o yaml , -o wide ).

kubectl describe kubectl describe pod web-app-54b9d-x8z2 Show detailed resource state, status conditions, and historical cluster events.

kubectl logs kubectl logs -f web-app-54b9d-x8z2 -c nginx-container Stream container logs ( -f follow, -p previous crashed container instance).

kubectl exec kubectl exec -it web-app-54b9d-x8z2 -- /bin/sh Execute interactive shell command inside a running container.

kubectl explain kubectl explain deployment.spec.template.spec Inspect API field documentation and schema requirements directly from CLI.