Skip to content

Commit

Permalink
docs: user documentation for NFS (#315)
Browse files Browse the repository at this point in the history
  • Loading branch information
@tmilos77
tmilos77 authored Jul 5, 2024
1 parent cf165e7 commit e4187c0
Show file tree
Hide file tree
Showing 16 changed files with 543 additions and 27 deletions.
14 changes: 0 additions & 14 deletions .github/workflows/lint-markdown-links.yml
View file

This file was deleted.

24 changes: 24 additions & 0 deletions .github/workflows/pr-docu-check.yaml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
name: PR Docu Checks

on:
pull_request:
branches:
- "main"
- "release-*"
workflow_dispatch:

jobs:
markdown-link-check:
runs-on: ubuntu-latest
steps:
- name: Checkout repo
uses: actions/checkout@v4
- name: Install node.js
uses: actions/setup-node@v4
with:
node-version: '20.x'
- name: Install md-check-link
run: npm install -g md-check-link
- name: Verify links
run: |
md-check-link -q -n 8 -c https://raw.githubusercontent.com/kyma-project/md-check-link/main/.mlc.config.json ./
4 changes: 2 additions & 2 deletions docs/technical/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Cloud Control reconcilers are doing local reconciliation of `cloud-control.kyma-
Both set of reconcilers have to also maintain the status of the resources they reconcile. This mean that Cloud Control reconcilers will observe the status of the cloud resources and project it into the status of the Cloud Control resources in KCP. And that Cloud Resource reconcilers will observe the status of the Cloud Control resources and project it into the status of the Cloud Resource resources in SKR.


![API and Reconcilers](./assets/api%20and%20reconcilers.png "API and Reconcilers")]
![API and Reconcilers](./assets/api-and-reconcilers.png "API and Reconcilers")]

## KCP Cloud Control Controller Manager

Expand All @@ -31,7 +31,7 @@ Due to the non-scalable concurrent reconciliation of large number of clusters th

The reconciler facing API like `Reconcile()` and `.SetupWithManager()` functions will remain as close as possible to the one defined by controller-runtime and used by Kubebuilder.

![SKR Controller Manager](./assets/skr%20controller%20manager.png)
![SKR Controller Manager](./assets/skr-controller-manager.png)


## CloudControl Scope resource
Expand Down
0 ...cal/assets/api and reconcilers.excalidraw → ...cal/assets/api-and-reconcilers.excalidraw
View file
File renamed without changes.
0 .../technical/assets/api and reconcilers.png → .../technical/assets/api-and-reconcilers.png
View file
File renamed without changes
0 .../assets/skr controller manager.excalidraw → .../assets/skr-controller-manager.excalidraw
View file
File renamed without changes.
0 ...chnical/assets/skr controller manager.png → ...chnical/assets/skr-controller-manager.png
View file
File renamed without changes
21 changes: 21 additions & 0 deletions docs/user/05-glossary.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Glossary

> [!TIP]
> The terms in the list are ordered alphabetically.
| Term | Description | Useful links |
|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|
| AWS | Amazon Web Services is a subsidiary of Amazon that provides on-demand cloud computing platforms and APIs. | [Amazon Web Services, Inc.](https://aws.amazon.com/) |
| AWS EFS | Amazon Elastic File System is a cloud storage service provided by Amazon Web Services designed to provide scalable, elastic, concurrent with some restrictions, and encrypted file storage that can be mounted by NFS protocol to the Kyma cluster workloads and used in RWX access mode. | [Amazon Elastic File System](https://aws.amazon.com/efs/) |
| Azure | Microsoft Azure, or just Azure, is the cloud computing platform developed by Microsoft. It offers management, access and development of applications and services to individuals, companies, and governments through its global infrastructure. | [Microsoft Azure](https://azure.microsoft.com/) |
| CIDR | Classless Inter-Domain Routing is a bitwise, prefix-based standard for the representation of IP address ranges. It facilitates routing by allowing blocks of addresses to be grouped into single entry. | [Classless Inter-Domain Routing](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) |
| Cloud | Cloud computing is the on-demand availability of computer system resources, especially data storage and computing power, without direct active management by the user. Large clouds often have functions distributed over multiple locations, each of which is a data center. | |
| Cloud provider | An IT company that provides on-demand, scalable computing resources like computing power, data storage, or applications over the internet. | |
| Cloud resources | A virtualized environment or IT service provided by the Cloud provider, like compute, data storage, analytics... | |
| GCP | Google Cloud Platform, offered by Google, is a suite of cloud computing services that provides a series of modular cloud services including computing, data storage, data analytics, and machine learning, alongside a set of management tools. | [Google Cloud Platform](https://cloud.google.com/) |
| GCP Filestore | A managed GCP file storage service for cloud applications that can be mounted by NFS protocol to the Kyma cluster workloads and used in RWX access mode. | [GCP file storage service](https://cloud.google.com/filestore?hl=en) |
| IP Address | Internet Protocol address is a unique address that identifies a device on the internet or a local network. | |
| IP Address range | A set of consecutive IP addresses, usually a network routing target expressed in the CIDR notation. | |
| Network routing | The process of selecting a path from source to destination node across one or more networks. | |
| RWX | Persistent Volume ReadWriteMany access mode. | [Kubernetes Persistent Volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#introduction) |
| VPC Network | Virtual Private Cloud network is a virtual version of a physical network that is implemented inside the cloud provider production network by using special netowrk virtualization software. | |
51 changes: 41 additions & 10 deletions docs/user/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,45 @@
> **TIP:** Apart from the {Module Name} heading, you can use your own titles for the remaining sections. You can also add more module-specific sections.

# {Module Name}
> Modify the title and insert the name of your module. Use Heading 1 (H1).
# Cloud Manager Module

## Overview
> Provide a description of your module and its components. Describe its features and functionalities. Mention the scope and add information on the CustomResourceDefinitions (CRDs).
> You can divide this section to the relevant subsections.
## What is Cloud Manager Module?
Cloud Manager is a central component that manages access to additional hyperscaler resources from the
Kyma Runtime cluster. Its responsibility is to bring hyperscaler products/resources into the Kyma cluster
in a secure way. Once Cloud Manager as a module is enabled in the Kyma cluster, Cloud Manager's features
give you access to the respective products and resources of the hyperscaler providers.

## Useful links (Optional)
> Provide links to the most relevant module documentation (tutorials, technical references, resources, etc.).
## Features

## Feedback (Optional)
> Describe how users can provide feedback.
Cloud Manager can provision the following cloud resources in the underlying cloud provider subscription:
* NFS server that can be used as a ReadWriteMany (RWX) volume in the Kyma cluster

## Architecture
Kyma Cloud Manager Operator runs in the Kyma Control Plane and does remote reconciliation on Kyma clusters that
have the Cloud Manager module enabled. It brings various Custom Resource Definitions (CRDs) each representing some
a specific cloud resource from the underlying cloud provider subscription.

## API / Custom Resources Definitions

### IpRange CR

The `iprange.cloud-resources.kyma-project.io` CRD describes the VPC network
IP range used for IP address allocation for cloud resources that require an IP address.
To learn more, read the [IpRange Custom Resource](./resources/04-10-iprange.md) documentation.


### AwsNfsVolume CR

The `awsnfsvolume.cloud-resources.kyma-project.io` CRD describes the AWS EFS
instance that can be used as RWX volume in the cluster.
To learn more, read the [AwsNfsVolume Custom Resource](./resources/04-20-10-aws-nfs-volume.md) documentation.


### GcpNfsVolume CR

The `gcpnfsvolume.cloud-resources.kyma-project.io` CRD describes the GCP Filestore
instance that can be used as RWX volume in the cluster.
To learn more, read the [GcpNfsVolume Custom Resource](./resources/04-30-10-gcp-nfs-volume.md) documentation.


## Related Information
To learn more about the Cloud Manager module, read the following:
* [Tutorials](./tutorials/README.md) that provide step-by-step instructions on creating, using and disposing cloud resources
12 changes: 11 additions & 1 deletion docs/user/_sidebar.md
View file
Original file line number Diff line number Diff line change
@@ -1 +1,11 @@
Use this file to create an unordered list of documents you want to display on the [Kyma website](https://kyma-project.io). The list serves to navigate through the user documentation. For more information, visit the [User documentation](https://github.com/kyma-project/community/blob/main/docs/guidelines/content-guidelines/01-user-docs.md) guide.
<!-- markdown-link-check-disable -->
* [Back to Kyma Home](/)
* [Cloud Manager Module](/cloud-manager/user/README.md)
* [Resources](/cloud-manager/user/resources/README.md)
* [IpRange](/cloud-manager/user/resources/04-10-iprange.md)
* [AwsNfsVolume](/cloud-manager/user/resources/04-20-10-aws-nfs-volume.md)
* [GcpNfsVolume](/cloud-manager/user/resources/04-30-10-gcp-nfs-volume.md)
* [Tutorials](/cloud-manager/user/tutorials/README.md)
* [AwsNfsVolume](/cloud-manager/user/tutorials/01-10-aws-nfs-volume.md)
* [Glossary of terms](./05-glossary.md)
<!-- markdown-link-check-enable -->
62 changes: 62 additions & 0 deletions docs/user/resources/04-10-iprange.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# IpRange Custom Resource

The `iprange.cloud-resources.kyma-project.io` custom resource (CR) specifies the VPC network
IP range that is used for IP address allocation for cloud resources that require an IP address.

You are allowed to have one IpRange CR. If there are multiple IpRange resources in the cluster, the
oldest one is reconciled and the other is ignored and put into the `Error` state.

Once an IpRange CR is created and reconciled, the Cloud Manager controller reserves the specified IP range
in the Virtual Private Cloud (VPC) network of the cluster in the underlying cloud provider. The IP address from that range is
assigned to the provisioned resources of the cloud provider that require IP addresses. Once a
cloud resource is assigned the local VPC network IP address it becomes functional and usable from the
cluster network and from the cluster workloads.

You don't have to create an IpRange resource. Once needed, it is automatically created
and Classless Inter-Domain Routing (CIDR) range automatically chosen adjacent to and with the same size as the cluster nodes IP range.
For most use cases this automatic allocation is sufficient.

You might be interested in manually creating an IpRange resource with specific CIDR in advanced cases of
VPC network topology when cluster and cloud resources are not the only resources in the network, so you
can avoid IP range collisions.

IpRange can be deleted and deprovisioned only if there are no cloud resources using it. In other words,
an IpRange and its underlying VPC network address range can be purged only if there are no cloud resources
using an IP from that range.


## Specification <!-- {docsify-ignore} -->

This table lists the parameters of the given resource together with their descriptions:

**Spec:**

| Parameter | Type | Description |
|-----------|--------|--------------------------------------------------------------------------------------|
| **cidr** | string | Specifies the CIDR of the IP range that will be allocated. For example, 10.250.4.0/22. |

**Status:**

| Parameter | Type | Description |
|-----------------------------------|------------|------------------------------------------------------------------------------------------------------------------------------------|
| **state** (required) | string | Signifies the current state of **CustomObject**. Its value can be either `Ready`, `Processing`, `Error`, `Warning`, or `Deleting`. |
| **conditions** | \[\]object | Represents the current state of the CR's conditions. |
| **conditions.lastTransitionTime** | string | Defines the date of the last condition status change. |
| **conditions.message** | string | Provides more details about the condition status change. |
| **conditions.reason** | string | Defines the reason for the condition status change. |
| **conditions.status** (required) | string | Represents the status of the condition. The value is either `True`, `False`, or `Unknown`. |
| **conditions.type** | string | Provides a short description of the condition. |


## Sample Custom Resource <!-- {docsify-ignore} -->

See an exemplary IpRange custom resource:

```yaml
apiVersion: cloud-resources.kyma-project.io/v1beta1
kind: IpRange
metadata:
name: my-range
spec:
cidr: 10.250.4.0/22
```
Loading

0 comments on commit e4187c0

Please sign in to comment.