Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add k8s docs for getting started, K8s Manifest and Helm #179

Merged
merged 32 commits into from
Feb 4, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
2027188
add k8s docs for getting started and helm
devpramod Sep 25, 2024
02de73e
fix formatting issues
devpramod Sep 27, 2024
16264b7
update toctree
devpramod Sep 27, 2024
d795981
upddate both docs
devpramod Oct 15, 2024
e633bdc
add k8s mainfest and add to getting started
devpramod Nov 19, 2024
65d24b4
update helm
devpramod Nov 19, 2024
8b2b120
remove manifest, keep helm, address minor changes
devpramod Dec 5, 2024
b30abe9
general container name instead of docker
devpramod Dec 5, 2024
b690735
default modeldir empty
devpramod Dec 5, 2024
7c00834
reranker add opea retrieved doc
devpramod Dec 5, 2024
1a29c71
add bfloat16 for helm
devpramod Dec 5, 2024
8f016c7
fix namespace link
devpramod Dec 5, 2024
4539f28
send users to deployment page
devpramod Dec 5, 2024
43cd5b7
remove manifest in index.rst
devpramod Dec 5, 2024
29a6d9f
link intro to helm
devpramod Dec 5, 2024
00d0493
added note for PVC
devpramod Dec 11, 2024
28a3773
update helm key components
devpramod Dec 11, 2024
b01b081
minor fix in note
devpramod Dec 11, 2024
25a5e4e
Update k8s_helm.md hardware prereq
devpramod Dec 17, 2024
f3fe209
Update examples/ChatQnA/deploy/k8s_helm.md
devpramod Jan 14, 2025
393eff1
Update examples/ChatQnA/deploy/k8s_helm.md
devpramod Jan 14, 2025
e99e466
Update k8s_helm.md
devpramod Jan 14, 2025
e392678
Update k8s_getting_started.md
devpramod Jan 14, 2025
b5259f8
make helm command generic
devpramod Jan 21, 2025
9c4a3fa
fix path
devpramod Jan 21, 2025
3c3d997
run port forward processes in the background
devpramod Jan 21, 2025
9d7c1ed
remove backup files
devpramod Jan 27, 2025
8e468c9
update toctree
devpramod Jan 27, 2025
8bac9bd
fix markdown format
devpramod Jan 27, 2025
d68883c
fix typos, fix path toctree
devpramod Jan 27, 2025
4b39da2
toctree directive for Kubernetes
devpramod Jan 27, 2025
ef130d0
Merge branch 'main' into main
mkbhanda Feb 4, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions examples/ChatQnA/ChatQnA_Guide.rst
Original file line number Diff line number Diff line change
Expand Up @@ -224,9 +224,11 @@ Single Node
Kubernetes
**********

* Xeon & Gaudi with GMC
* Xeon & Gaudi without GMC
* Using Helm Charts
.. toctree::
:maxdepth: 1

Getting Started <deploy/k8s_getting_started>
Kubernetes Deployment with Helm on Xeon <deploy/k8s_helm>

Cloud Native
************
Expand Down Expand Up @@ -405,4 +407,4 @@ Log in to Grafana using the default credentials:
Summary and Next Steps
=======================

TBD
TBD
78 changes: 78 additions & 0 deletions examples/ChatQnA/deploy/k8s_getting_started.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
# Getting Started with Kubernetes for ChatQnA
devpramod marked this conversation as resolved.
Show resolved Hide resolved

## Introduction

Kubernetes is an orchestration platform for managing containerized applications, ideal for deploying microservices based architectures like ChatQnA. It offers robust mechanisms for automating deployment, scaling, and operations of application containers across clusters of hosts. Kubernetes supports different deployment modes for ChatQnA, which cater to various operational preferences. We will see how ChatQnA can be deployed via `Helm`, a package manager for Kubernetes that simplifies the deployment, management, and versioning of Kubernetes applications using pre-configured templates called charts.


This guide will provide detailed instructions on using Kubernetes and Helm. If you're already familiar with Kubernetes, feel free to skip ahead to [Helm Deployment](./k8s_helm.md)

### Kubernetes Cluster and Development Environment

**Setting Up the Kubernetes Cluster:** Before beginning deployment for the ChatQnA application, ensure that a Kubernetes cluster is ready. For guidance on setting up your Kubernetes cluster, please refer to the comprehensive setup instructions available at [Kubernetes Installation Options](https://opea-project.github.io/latest/guide/installation/k8s_install/README.html).

**Development Pre-requisites:** To prepare for the deployment, familiarize yourself with the necessary development tools and configurations by visiting the [GenAI Infrastructure development page](https://opea-project.github.io/latest/GenAIInfra/DEVELOPMENT.html). This page covers all the essential tools and settings needed for effective development within the Kubernetes environment.


**Understanding Kubernetes Deployment Tools and Resources:**

- **kubectl**: This command-line tool allows you to deploy applications, inspect and manage cluster resources, and view logs. For instance, `kubectl apply -f chatqna.yaml` would be used to deploy resources defined in a manifest file.

- **Pods**: Pods are the smallest deployable units created and managed by Kubernetes. A pod typically encapsulates one or more containers where your application runs.

**Verifying Kubernetes Cluster Access with kubectl**
```bash
kubectl get nodes
```

devpramod marked this conversation as resolved.
Show resolved Hide resolved
#### Create and Set Namespace
devpramod marked this conversation as resolved.
Show resolved Hide resolved
A Kubernetes namespace is a logical division within a cluster that is used to isolate different environments, teams, or projects, allowing for finer control over resources and access management. To create a namespace called `chatqa`, use:
```bash
kubectl create ns chatqa
```
When deploying resources (like pods, services, etc.) into your specific namespace, use the `--namespace` flag with `kubectl` commands, or specify the namespace in your resource configuration files.

To deploy a pod in the `chatqa` namespace:
```bash
kubectl apply -f your-pod-config.yaml --namespace=chatqa
```
devpramod marked this conversation as resolved.
Show resolved Hide resolved
If you want to avoid specifying the namespace with every command, you can set the default namespace for your current context:
```bash
kubectl config set-context --current --namespace=chatqa
```

Some commonly used kubectl commands and their functions, assuming that you have set your namespace context appropriately are:
|Command |Function |
|------------------------------- |-----------------------------|
|`kubectl describe pod <pod-name>` | Provides detailed information about a specific pod, including its current state, recent events, and configuration details. |
|`kubectl delete -f <path-to-manifest>` | Deletes all the resources in the current namespace, which effectively removes all the managed pods and associated resources. |
|`kubectl get pods -o wide` | Retrieves a detailed list of all pods in the current namespace, including additional information like IP addresses and the nodes they are running on. |
|`kubectl logs <pod-name>` | Fetches the logs generated by a container in a specific pod, useful for debugging and monitoring application behavior. |
|`kubectl get svc` | Lists all services in the current namespace, providing a quick overview of the network services and their status.



### Using Helm Charts to Deploy

**What is Helm?** Helm is a package manager for Kubernetes, similar to how apt is for Ubuntu. It simplifies deploying and managing Kubernetes applications through Helm charts, which are packages of pre-configured Kubernetes resources.

#### Key Components of a Helm Chart

| Component |Description |
| --- | --- |
| `Chart.yaml` | This file contains metadata about the chart such as name, version, and description. |
| `values.yaml` | Overridable configuration values for the Helm chart deployment, used in the chart k8s object templates. |
| `templates/` Directory | Contains YAML templates for Kubernetes objects, typically one file per object type (e.g., deployment.yaml for Deployments, service.yaml for Services). For more details, refer to the Helm Templates Best Practices.

**Update Dependencies:**

- A script called **./update_dependency.sh** is provided which is used to update chart dependencies, ensuring all nested charts are at their latest versions.
devpramod marked this conversation as resolved.
Show resolved Hide resolved
- The command helm dependency update <chart-directory> updates the dependencies for the chart located in the specified directory (e.g., chatqna) based on the versions specified in its Chart.yaml file.

**Helm Install Command:**

- `helm install [RELEASE_NAME] [CHART_NAME]`: This command deploys a Helm chart into your Kubernetes cluster, creating a new release. It is used to set up all the Kubernetes resources specified in the chart and track the version of the deployment.
devpramod marked this conversation as resolved.
Show resolved Hide resolved

For more detailed instructions and explanations, you can refer to the [official Helm documentation](https://helm.sh/docs/).

Continue to [Helm Deployment](./k8s_helm.md) to deploy ChatQnA via Helm.
Loading