Skip to content

Commit

Permalink
[docs] refactor the Kubernetes guide
Browse files Browse the repository at this point in the history 
[docs] refactor the Kubernetes guide

Pull Request resolved: 425
  • Loading branch information
@blinkov
blinkov authored and blinkov committed Dec 1, 2023
1 parent f7e8a83 commit e766ad5
Show file tree
Hide file tree
Showing 23 changed files with 677 additions and 1,126 deletions.
2 changes: 1 addition & 1 deletion ydb/docs/en/core/deploy/_includes/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ This section provides information on deploying and configuring multi-node YDB cl

* [{#T}](../../cluster/system-requirements.md).
* [{#T}](../../cluster/topology.md).
* [Deployment in Kubernetes](../orchestrated/concepts.md).
* [Deployment in Kubernetes](../../getting_started/kubernetes.md).
* [Deployment on virtual and physical servers](../manual/deploy-ydb-on-premises.md).
* [Configuration](../configuration/config.md).
* [BlobStorage production configurations](../../administration/production-storage-config.md).
Expand Down
212 changes: 0 additions & 212 deletions ydb/docs/en/core/deploy/orchestrated/_includes/ydb-kubernetes-operator.md
View file
Original file line number Diff line number Diff line change
@@ -1,212 +0,0 @@
# Installing a cluster

## Install the {{ ydb-short-name }} controller in the {#install-ydb-controller} cluster

Install {{ ydb-short-name }} in the standard configuration:

{% list tabs %}

- CLI

Run the command:

```bash
helm install ydb-operator ydb/ydb-operator
```

* `ydb-operator`: The release name.
* `ydb/ydb-operator`: The name of the chart in the repository you added earlier.

Result:

```text
NAME: ydb-operator
LAST DEPLOYED: Thu Aug 12 19:32:28 2021
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None
```

{% endlist %}

## Create a {{ ydb-short-name }} cluster {#create-cluster}

Apply the manifest for creating a {{ ydb-short-name }} cluster:

{% list tabs %}

- CLI

Run the command:

```bash
kubectl apply -f samples/storage-block-4-2.yaml
```

This command creates a StatefulSet object that describes a set of containers with stable network IDs and disks assigned to them, as well as Service and ConfigMap objects that are required for the cluster to work.

You can check the progress of {{ ydb-short-name }} cluster creation using the following commands:

```bash
kubectl get storages.ydb.tech
kubectl describe storages.ydb.tech
```

Wait until the status of the Storage resource changes to `Ready`.

{% endlist %}

{% note warning %}

The cluster configuration is static. The controller won't process any changes when the manifest is reapplied. You can only update cluster parameters such as version or disk size by creating a new cluster.

{% endnote %}

The standard configuration includes the minimum required 9 storage nodes, 80 GB each.

{% include [_includes/storage-device-requirements.md](../../../_includes/storage-device-requirements.md) %}

## Create a database {#create-database}

Apply the manifest for creating a database:

{% list tabs %}

- CLI

Run the command:

```bash
kubectl apply -f samples/database.yaml
```


{% note info %}

The `.spec.storageClusterRef.name` key value must match the name of the storage resource of the cluster part.

{% endnote %}

After processing the manifest, a StatefulSet object that describes a set of dynamic nodes is created. The created database will be accessible from inside the {{ k8s }} cluster by the `database-sample` DNS name or the `database-sample.<namespace>.svc.cluster.local` FQDN, where `namespace` indicates the namespace that the release was installed. The database is connected to through port `2135`.

View the status of the created resource:

```bash
kubectl describe database.ydb.tech

Name: database-sample
Namespace: default
Labels: <none>
Annotations: <none>
API Version: ydb.tech/v1alpha1
Kind: Database
...
Status:
State: Ready
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Provisioning 8m10s ydb-operator Resource sync is in progress
Normal Provisioning 8m9s ydb-operator Resource sync complete
Normal TenantInitialized 8m9s ydb-operator Tenant /root/database-sample created
```

The database is ready to run.

{% endlist %}

## Test the controller {#test-ydb}

Test how {{ ydb-short-name }} works:

{% list tabs %}

- CLI

1. Check that all nodes are in the `Ready` status:

```bash
kubectl get pods

NAME READY STATUS RESTARTS AGE
database-sample-0 1/1 Running 0 1m
database-sample-1 1/1 Running 0 1m
database-sample-2 1/1 Running 0 1m
database-sample-3 1/1 Running 0 1m
database-sample-4 1/1 Running 0 1m
database-sample-5 1/1 Running 0 1m
storage-sample-0 1/1 Running 0 1m
storage-sample-1 1/1 Running 0 1m
storage-sample-2 1/1 Running 0 1m
storage-sample-3 1/1 Running 0 1m
storage-sample-4 1/1 Running 0 1m
storage-sample-5 1/1 Running 0 1m
storage-sample-6 1/1 Running 0 1m
storage-sample-7 1/1 Running 0 1m
storage-sample-8 1/1 Running 0 1m
```

1. Start a new pod using the {{ ydb-short-name }} CLI:

```bash
kubectl run -it --image=cr.yandex/yc/ydb:21.4.30 --rm ydb-cli bash
```

1. Query the {{ ydb-short-name }} database:

```bash
ydb \
--endpoint grpc://database-sample-grpc:2135 \
--database /root/database-sample \
table query execute --query 'select 1;'
```

* `--endpoint`: Database endpoint.
* `--database`: The name of the created database.
* `--query`: Query text.

Result:

```text
┌─────────┐
| column0 |
├─────────┤
| 1 |
└─────────┘
```

For more on {{ ydb-short-name }} CLI commands, see the [documentation](../../../reference/ydb-cli/index.md).

{% endlist %}

## Release the resources you don't use {#cleanup}

If you no longer need the created resources, delete them:

{% list tabs %}

- CLI

1. To delete a {{ ydb-short-name }} database, just delete the `Database` resource mapped to it:

```bash
kubectl delete database.ydb.tech database-sample
```

1. To delete a {{ ydb-short-name }} cluster, run the following commands:

```bash
kubectl delete storage.ydb.tech storage-sample
kubectl delete pvc -l app.kubernetes.io/name=ydb
```

1. To remove the {{ ydb-short-name }} controller from the {{ k8s }} cluster, delete the release created by Helm:

```bash
helm delete ydb-operator
```

* `ydb-operator`: The name of the release that the controller was installed under.

{% endlist %}
92 changes: 0 additions & 92 deletions ydb/docs/en/core/deploy/orchestrated/aws_eks.md
View file
Original file line number Diff line number Diff line change
@@ -1,92 +0,0 @@
# Deploying {{ ydb-short-name }} in AWS EKS

To use [{{ k8s }}](https://kubernetes.io/) to create a cluster [{{ ydb-short-name }}]{% if lang == "en" %}(https://cloud.yandex.com/en/docs/ydb/){% endif %}{% if lang == "ru" %}(https://cloud.yandex.ru/docs/ydb/){% endif %}, follow the steps below.

## Before you start {#before-begin}

1. Configure `awscli` and `eksctl` to work with AWS resources according to the [documentation](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-eksctl.html).

1. Install the {{ k8s }} CLI [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl).

1. Create a {{ k8s }} cluster.

You can use an existing {{ k8s }} cluster or create a new one.

{% note warning %}

Make sure that you're using {{ k8s }} version 1.20 or higher.

{% endnote %}

{% cut "How to create {{ k8s }} cluster" %}

{% list tabs %}

- CLI

```bash
eksctl create cluster \
--name yandex-database \
--nodegroup-name standard-workers \
--node-type c5a.2xlarge \
--nodes 3 \
--nodes-min 1 \
--nodes-max 4
```

{% endlist %}

A {{ k8s }} cluster named `yandex-database` is created. The `--node-type` flag indicates that the cluster is deployed using `c5a.2xlarge` (8vCPUs, 16 GiB RAM) instances. This meets our guidelines for running {{ ydb-short-name }}.

It takes 10 to 15 minutes on average to create a cluster. Wait for the process to complete before proceeding to the next step of {{ ydb-short-name }} deployment. The kubectl configuration will be automatically updated to work with the cluster after it is created.

{% endcut %}

1. Install the {{ k8s }} [Helm 3](https://helm.sh/docs/intro/install/) package manager.

1. Add a repository for {{ yandex-cloud }} to Helm:

{% list tabs %}

- CLI

Run the command:

```bash
helm repo add ydb https://charts.ydb.tech/
```
* `ydb`: The repository alias.
* `https://charts.ydb.tech/`: The repository URL.

Output:

```text
"ydb" has been added to your repositories
```

{% endlist %}

1. Update the Helm chart index:

{% list tabs %}

- CLI

Run the command:

```bash
helm repo update
```

Output:

```text
Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "ydb" chart repository
Update Complete. ⎈Happy Helming!⎈
```
{% endlist %}
{% include notitle [ydb-kubernetes-operator](_includes/ydb-kubernetes-operator.md) %}
31 changes: 0 additions & 31 deletions ydb/docs/en/core/deploy/orchestrated/concepts.md
View file
Original file line number Diff line number Diff line change
@@ -1,31 +0,0 @@
# Overview

Deploying {{ ydb-short-name }} in {{ k8s }} is a simple and easy way to install {{ ydb-short-name }}. With {{ k8s }}, you can use a universal approach to managing your application in any cloud provider. This guide provides instructions on how to deploy {{ ydb-short-name }} in [{{ managed-k8s-full-name}}](yc_managed_kubernetes.md) and [AWS EKS](aws_eks.md).

{{ ydb-short-name }} is delivered as a Helm chart that is a package with templates of {{ k8s }} structures. You can deploy charts in the following environment:

1. The Helm package manager of version higher than 3.1.0 is installed.
1. {{ k8s }} version 1.20 or higher is used.
1. The kubectl command line tool is installed and cluster access is configured.
1. [Dynamic Volume Provisioning](https://kubernetes.io/docs/concepts/storage/dynamic-provisioning/) is supported in clusters.

For more information about Helm, see the [documentation]{% if lang == "en" %}(https://helm.sh/docs/){% endif %}{% if lang == "ru" %}(https://helm.sh/ru/docs/){% endif %}.

A Helm chart installs a controller in the {{ k8s }} cluster. It implements the logic required for deploying {{ ydb-short-name }} components. The controller is based on the [Operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) pattern.

{{ydb-short-name}} consists of two components:

* _Storage nodes_: Provide the data storage layer.
* _Dynamic nodes_: Implement data access and processing.

To deploy each of the components, just create an appropriate resource: [Storage](https://github.com/ydb-platform/ydb-kubernetes-operator/tree/master/samples/storage-block-4-2.yaml) or [Database](https://github.com/ydb-platform/ydb-kubernetes-operator/tree/master/samples/database.yaml) with the desired parameters. To learn more about the resource schema, follow [this link](https://github.com/ydb-platform/ydb-kubernetes-operator/tree/master/deploy/ydb-operator/crds).

After the chart data is processed by the controller, the following resources are created:

* [StatefulSet](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/): A workload controller that assigns stable network IDs and disk resources to each container.
* [Service](https://kubernetes.io/docs/concepts/services-networking/service/): An object that is used to access the created databases from applications.
* [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/): An object that is used to store the cluster configuration.

See the controller's source code [here](https://github.com/ydb-platform/ydb-kubernetes-operator). The Helm chart is in the `deploy` directory.
{{ydb-short-name}} containers are deployed using `cr.yandex/yc/ydb` images. Currently, they are only available as prebuilt artifacts.

Loading

0 comments on commit e766ad5

Please sign in to comment.