diff --git a/README.md b/README.md index 4545262..4b20a04 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# Kuesta Website +# KSOT Website -This repo contains the code of the [Kuesta documentation website](nttcom.github.io/kuesta-website), +This repo contains the code of the [ksot documentation website](nttcom.github.io/ksot-website), built using [Hugo](https://gohugo.io/) and the [docsy](https://www.docsy.dev/) theme. ## Requirements diff --git a/config.toml b/config.toml index 4e91b52..5e03d9f 100644 --- a/config.toml +++ b/config.toml @@ -1,5 +1,5 @@ baseURL = "/" -title = "Kuesta" +title = "ksot" # Language settings contentDir = "content/en" @@ -44,7 +44,7 @@ pygmentsStyle = "tango" [[menu.main]] name = "GitHub" weight = 101 -url = "https://github.com/nttcom/kuesta" +url = "https://github.com/nttcom/ksot" # Configure how URLs look like per section. @@ -66,14 +66,14 @@ id = "UA-00000000-0" [languages] [languages.en] -title = "Kuesta" +title = "ksot" description = "CUE-based Network IaC on Kubernetes" languageName ="English" # Weight used for sorting. weight = 1 [languages.ja] -title = "Kuesta" +title = "ksot" description = "CUE-based Network IaC on Kubernetes" languageName ="Japanese" contentDir = "content/ja" @@ -121,9 +121,9 @@ version = "0.0" url_latest_version = "https://example.com" # Repository configuration (URLs for in-page links to opening issues and suggesting changes) -github_repo = "https://github.com/nttcom/kuesta-website" +github_repo = "https://github.com/nttcom/ksot-website" # An optional link to a related project repo. For example, the sibling repository where your product code lives. -github_project_repo = "https://github.com/nttcom/kuesta" +github_project_repo = "https://github.com/nttcom/ksot" # Specify a value here if your content directory is not in your repo's root directory # github_subdir = "" @@ -166,8 +166,8 @@ sidebar_search_disable = false [params.ui.feedback] enable = true # The responses that the user sees after clicking "yes" (the page was helpful) or "no" (the page was not helpful). -yes = 'Glad to hear it! Please tell us how we can improve.' -no = 'Sorry to hear that. Please tell us how we can improve.' +yes = 'Glad to hear it! Please tell us how we can improve.' +no = 'Sorry to hear that. Please tell us how we can improve.' # Adds a reading time to the top of each doc. # If you want this feature, but occasionally need to remove the Reading time from a single page, @@ -179,9 +179,9 @@ enable = false # End user relevant links. These will show up on left side of footer and in the community page if you have one. [[params.links.user]] name = "GitHub Discussions" - url = "https://github.com/nttcom/kuesta/discussions" + url = "https://github.com/nttcom/ksot/discussions" icon = "fab fa-github" - desc = "Ask questions and discuss abount Kuesta." + desc = "Ask questions and discuss abount ksot." #[[params.links.user]] # name = "User mailing list" @@ -201,7 +201,7 @@ enable = false # Developer relevant links. These will show up on right side of footer and in the community page if you have one. [[params.links.developer]] name = "GitHub" - url = "https://github.com/nttcom/kuesta" + url = "https://github.com/nttcom/ksot" icon = "fab fa-github" desc = "Development takes place here!" #[[params.links.developer]] diff --git a/content/en/_index.html b/content/en/_index.html index 8769a0a..6beb6c4 100644 --- a/content/en/_index.html +++ b/content/en/_index.html @@ -1,21 +1,18 @@ +++ -title = "Kuesta" -linkTitle = "Kuesta" +title = "K-SOT" +linkTitle = "K-SOT" +++ {{< blocks/cover title="" subtitle="" image_anchor="top" color="dark" >}}
- Kuesta -
-
- CUE-based Network IaC on Kubernetes + K-SOT
}}"> Learn More - + Download
@@ -23,7 +20,7 @@ {{% blocks/lead color="white" %}} -**Kuesta** is an open source framework for network configuration, enabling
+**K-SOT** is an open source framework for network configuration, enabling
Infrastructure-as-Code of network devices. It provides us a rich network automation
by adopting cloud-native best practices of IaC and GitOps. diff --git a/content/en/docs/CLI/_index.md b/content/en/docs/CLI/_index.md deleted file mode 100644 index 4a5c855..0000000 --- a/content/en/docs/CLI/_index.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: "CLI" -linkTitle: "CLI" -weight: 5 -description: > - Instructions of Command-Line Interface. ---- - -Kuesta supports IaC configuration update via both gNMI and `kuesta` CLI. -`kuesta` CLI helps you when you would like to manage your configuration repository manually using `kuesta`, or integrate with CI like GitHub Actions or GitHub Apps. - - -## Installation - -Download `kuesta` CLI as a tarball from the [kuesta Releases page](https://github.com/nttcom/kuesta/releases). -After downloading the tarball, extract it to your PATH: - -```bash -# Replace YOUR-DOWNLOADED-FILE with the file path of your own. -sudo tar xvzf YOUR-DOWNLOADED-FILE -C /usr/local/bin/ kuesta -``` - -### Build from source - -If you would like to build kuesta from the source, set up your Go environment using Go 1.18 or higher, and run the following: - -```bash -git clone https://github.com/nttcom/kuesta.git -cd kuesta -go build -o kuesta main.go -``` - -Then move built binary to your PATH. - - -## Usage - -You can perform an IaC configuration update without using kuesta-server by the following steps: - -1: Clone the GitHub Repository you want to use as the configuration manifest source. - -2: Update service configs. - -3: Add these updated services to git Index. - -4: Run `kuesta service apply` to perform data mapping from the service config to the device config as follows: - -```bash -kuesta service apply -p= -``` - -Data mapping from the service config to the device config will be performed only for git-staged services, all unstaged changes will be skipped. - -5: Run `kuesta git commit` to create git PullRequest on your configuration manifest repository. If authentication to git provider is required, -use `--git-token` command flag or `KUESTA_GIT_TOKEN` environment value to provide GitHub private access token. - -```bash -kuesta git commit -p -r -``` - -For more information about available commands and flags, run `kuesta help`. diff --git a/content/en/docs/Concepts/_index.md b/content/en/docs/Concepts/_index.md index 1c1bac5..426df9b 100644 --- a/content/en/docs/Concepts/_index.md +++ b/content/en/docs/Concepts/_index.md @@ -3,64 +3,30 @@ title: "Concepts" linkTitle: "Concepts" weight: 3 description: > - Learn more about the core concepts of Kuesta. + Concepts, architecture, and other technical information about K-SOT. --- -## Network Configuration as Code with CUE +## Network Configuration as Code with Go -Kuesta supports creating an abstracted high-level configuration layer to expose easy high-level data model and API. -The configuration data models of the network devices have lots of networking capabilities therefore are too much detailed and complicated, they are not suitable for the resource model of the Infrastructure as Code. -To provide a data model which can represent the user intent easily, an abstracted high-level data model is required to hide the complicated actual device configurations. -In addition, the high-level data model which effects multiple network device configs is needed for domain-wide abstraction such as E2E connectivity. +K-SOT supports abstracting complex network device configurations and exposing a high-level data model and API that can easily describe user intent. The data model of a network device is too detailed and complex to be treated as an Infrastructure as Code resource model, as it provides a multitude of networking functions. In order to provide a data model that can easily represent user intent, a high-level data model is needed that hides the complexity and abstracts it in an understandable manner. In addition, to achieve a model that abstracts the entire domain, such as an E2E connection, requires a data model that is configured across multiple network devices. -These high-level data model abstraction causes the additional complexity of the high-to-low data mapping logic. -The relations between the high-level model and the low-level actual device configs are many-to-many, we need to consider performing data composition in addition to high-to-low data mapping without data loss, conflicts, and type constraint violation. -A simple text-templating approach using Python/Jinja is not enough to solve this complex problem. +With such abstraction to a high-level model, the data mapping from the high-level model to the low-level equipment configurations becomes very complex. +Because of the many-to-many relationship between the upper and lower models, in addition to data mapping, data synthesis must also be performed simultaneously. At this time, care must be taken to avoid missing data, conflicts, and data constraint violations. +A simple text template approach using Python/Jinja is difficult to solve this complex problem. -Kuesta uses [CUE](https://github.com/cue-lang/cue) as a programming language of high-to-low data mapping logic. CUE is a configuration language specialized in data unification and validation, and is well-suited for the above usecase for the following reasons: -- CUE enables us to unify multiple document-tree in the arbitrary layer. CUE is designed to ensure combining CUE values in any order always gives the same result (associative, commutative, and idempotent). -- CUE merges types and values into a single concept. Even types and constraints are the kind of value, the only difference between them is that they do not have concrete value. Due to this novel approach, we can declare constraints and schema simply and efficiently in the configuration data itself. -- CUE is highly programmable and supports software coding practices like templating and modularization. We can take the same advantages as if we use general-purpose language. +With K-SOT, the data mapping logic from the upper model to the lower model can be written in Go. In addition, data composition can be implemented without user awareness. -To learn more about CUE, see ["cuelang.org"](https://cuelang.org/docs/about/). +## Data Management with GitHub +K-SOT provides data management via GitHub for network device configurations. It is intended to be a single source of truth (SSoT) that can be trusted by declaratively describing the configuration of the entire network and versioning it in a GitHub repository -## GitOps +## Components of K-SOT -Kuesta provides GitOps for network configuration. It aims to describe the entire network configuration declaratively and version controlled in a Git repository, as a Single Source of Truth(SSoT). -The configuration process is totally automated so that the deployed network configuration matches the state specified in a repository. All you have to do to switch the network configuration or rollback is to change the Git branch HEAD to the revision you want to deploy. +K-SOT consists of the following components: -Kuesta selects Pull-based approach for the following reasons: -- To detect the configuration drift between the desired config in the configuration repository and the actual config stored in devices, whenever the device config is updated. -- To ensure that the entire network configuration stored at the SSoT git repository is deployed to the devices with the prepared deploy pipeline, without inserting any configuration changes. -- To avoid aggregating all device credentials and providing them to the single god-mode configuration system. Device credentials are stored as the Kubernetes Secret resource, and you can integrate with public clouds' SecretManager to manage these credentials more securely using OSS tools like ExternalSecrets Operator. +- **nb-server** receives the service model and performs derivation of the device configuration. -For more information about GitOps, take a look at [“What is GitOps?”](https://www.gitops.tech/#what-is-gitops). +- **github-server** updates GitHub. - -## Kubernetes Custom Operator - -Kuesta uses the Kubernetes reconciliation loop and the operator pattern as an engine of Infrastructure as Code. -Kubernetes is a well-known container orchestration tool, but it can be extended to automate deploying any external resources including network devices. -Kuesta consists of multiple Kubernetes custom operators to perform GitOps, distributed transaction coordinator, and the driver to configure the network devices. - -You can extend Kuesta to support new vendors' devices or new versions by implementing Kubernetes custom operator for them as a device driver. - - -## The components of Kuesta - -Kuesta consists of the following components: - -- **kuesta-server** is the core api-server of Kuesta. It exposes gNMI to integrate with the external 3rd-party system, performs high-to-low data mapping and data composition, and creates new git-commit and PullRequest for GitOps. - -- **kuesta-aggregator** aggregates the actual device config changes and creates a new git-commit to persist the config change history. - -- **FluxCD source-controller** detects manifest changes of the specified Git repository at `GitRepository` Kubernetes custom resource. - -- **kuesta-provisioner** consists of the `gitrepository-watcher` controller and `DeviceRollout` Kubernetes custom resource. `gitrepository-watcher` watches `GitRepository` status to detect the manifest changes and updates `DeviceRollout` status to `running` when change is detected, which triggers the device config update transaction. - -To configure network devices using Kuesta, you must prepare your own Kubernetes custom operator to configure your target devices. -It is recommended to use [kubebuilder](https://github.com/kubernetes-sigs/kubebuilder) which is the powerful framework to build your Kubernetes custom operator. -You can also start from [device-operator](https://github.com/nttcom/kuesta/tree/main/device-operator) used at the ["Getting started"](/docs/getting-started), the sample Kubernetes custom operator designed to configure OpenConfig/gNMI device. -It is built using kubebuilder. +- **sb-server** submits the configuration to the device. diff --git a/content/en/docs/Contribution guidelines/_index.md b/content/en/docs/Contribution guidelines/_index.md deleted file mode 100644 index 9140aa1..0000000 --- a/content/en/docs/Contribution guidelines/_index.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: "Contribution Guidelines" -linkTitle: "Contribution Guidelines" -weight: 10 -description: How to contribute to Kuesta ---- - -Kuesta is an open source project and we love getting patches and contributions to make Kuesta and its docs even better. - - -## Contributing to Kuesta - - -### Creating PullRequest - -All submissions, including submissions by project members, require review. We -use GitHub PullRequest for this purpose. Consult -[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more -information on using pull requests. - - -### Creating issues - -If you have found something that isn't working the way you'd expect, but you're not sure how to fix it yourself, please create an [issue](https://github.com/nttcom/kuesta/issues). - - -## How to run the test suites - -To run the whole test suites of all kuesta components: - -```bash -make test-all -``` - -To run the specified component test suites only, run the following at the top of the component dir: - -```bash -make test -``` - -For lint, install [golangci-lint](https://golangci-lint.run/usage/install/#local-installation) in advance, then run at the top of kuesta repo: - -```bash -make lint-all -``` - -If you want to run Kuesta locally, see ["Installtaion"](/docs/installation) page. \ No newline at end of file diff --git a/content/en/docs/Getting started/_index.md b/content/en/docs/Getting started/_index.md index 5630e43..45b7557 100644 --- a/content/en/docs/Getting started/_index.md +++ b/content/en/docs/Getting started/_index.md @@ -3,517 +3,409 @@ title: "Getting Started" linkTitle: "Getting Started" weight: 1 description: > - Get started with Kuesta. + Let's move K-SOT! --- -This tutorial shows you how to +In this tutorial, you will build K-SOT and check its operation by following the steps below. -1. Create a local Kubernetes cluster. -2. Install Kuesta. -3. Run device emulator. -4. Create new service and configure the device emulators by GitOps. +1. Create a local Kubernetes cluster +2. Create a Github repository for verification +3. Install K-SOT and configure various files +4. Start up the device emulator +5. Deploy K-SOT +6. Operation check +## Advance preparation -## Prerequisites +1. Install [golang (v1.21.0+))](https://go.dev/doc/install). You will need it to write the device configuration derivation logic. +2. Install [docker (v20.10.24+)](https://docs.docker.com/engine/install). Required to run KIND. +3. Install [kind (v0.12.0+)](https://kind.sigs.k8s.io/docs/user/quick-start/). Used to build local Kubernetes clusters. +4. Install [kubectl (v1.25.4+)](https://kubernetes.io/docs/tasks/tools/). Used to execute commands against a Kubernetes cluster. -1. [Install golang (v1.20.4+)](https://go.dev/doc/install) to use controller-tools. -2. [Install docker (v20.10.24+)](https://docs.docker.com/engine/install) to use cluster in kind. -3. [Install kind (v0.12.0+)](https://kind.sigs.k8s.io/docs/user/quick-start/) to set up local Kubernetes cluster. -4. [Install kubectl (v1.25.4+)](https://kubernetes.io/docs/tasks/tools/) to run commands against Kubernetes clusters. -5. [Install cue (v0.4.x)](https://cuelang.org/docs/install/) to run Kuesta installation script. -6. [Install gnmic (v0.26.0+)](https://gnmic.kmrd.dev/install/) to perform gNMI request to kuesta server. +## 1. Create a local Kubernetes cluster - -## Create a local Kubernetes cluster - -Create a local Kubernetes cluster with kind. +Run the following command to start a local Kubernetes cluster. ```bash -kind create cluster +kind create cluster --name ksot-started ``` -You can check that the cluster was successfully created by running: +When execution is complete, confirm that the Kubernetes cluster has been successfully created by running the following command. ```bash kubectl cluster-info ``` -Then you will see an output similar to the following that confirms your local cluster is running: +If you see output similar to the following, the local cluster is working properly. -``` +```bash Kubernetes control plane is running at https://127.0.0.1:52096 CoreDNS is running at https://127.0.0.1:52096/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'. ``` -## Set up GitHub source repositories for testing - -To configure network devices using Kuesta's GitOps, you need to set up 2 GitHub repositories. One is for -the configuration source repository, and the other is for the update history of network devices' actual configuration status. -You can easily set up these repositories using [Kuesta Example](https://github.com/nttcom/kuesta-example) repository as a template. -Repository must consist of lower case alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character. - -Run the following 2 times to create the repository pair: - -1. Click **Use this template** button of [Kuesta Example repository](https://github.com/nttcom/kuesta-example). -2. Select a name for your new repository and click **Create repository from template**. You can choose either public or private whichever you prefer. +## 2. Create a Github repository for verification +In order for K-SOT to manage the configuration of network devices using Github, a GitHub repository must be created. +Using the [K-SOT Example](https://github.com/nttcom/ksot-example) repository as a template, these repositories can be easily created. -## Install Kuesta and sample resources +Create a GitHub repository by doing the following -To install Kuesta and sample resources like device drivers and emulators, just run cue script: +1. Click on the **Use this template** button in the [K-SOT Example](https://github.com/nttcom/ksot-example) repository. -```bash -git clone https://github.com/nttcom/kuesta.git -cd kuesta/tool/install -cue install -``` +2. Enter a repository name and click the **Create repository from template** button. You can choose to make the repository public or private as you like. In this case, set the repository owner to the user's account and the repository name to ksot-example. -Provide required parameters according to the instructions: -The `GitHub repository for config` `GitHub repository for status` should specify each of the two Github repositories for verification that you have created. +## 3. Install K-SOT and configure various files +### Clone the K-SOT repository and initialize submodules. +Repository clone ```bash -GitHub repository for config: https://github.com// -GitHub repository for status: https://github.com// -GitHub username: -GitHub private access token: -Are these git repositories private? (yes|no): yes -Do you need sample driver and emulator for trial?: (yes|no) yes - ---- -GitHub Config Repository: https://github.com// -GitHub Status Repository: https://github.com// -GitHub Username: -GitHub Access Token: *** -Use Private Repo: true - -Image Registry: ghcr.io/nttcom/kuesta -Version: latest -Deploy sample driver and emulator: true ---- - -Continue? (yes|no) yes +git clone https://github.com/nttcom/ksot.git ``` - -For Kuesta to perform git-push and create pull-request, you need to prepare a GitHub [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) (PAT) and provide it in the installation(classic is recommended). -Since PAT provided here is stored only in Secret resources on your local Kubernetes cluster, you can remove them safely and completely by [cleaning up your local cluster](/docs/getting-started/#clean-up). - -After running an installation script, you can see what is installed by running `kubectl` commands: - -1: Custom Resource Definitions(CRDs): -```bash -kubectl get customresourcedefinitions.apiextensions.k8s.io -```` - +Submodule initialization ```bash -NAME CREATED AT -buckets.source.toolkit.fluxcd.io 2023-01-10T06:31:20Z -certificaterequests.cert-manager.io 2023-01-10T06:31:19Z -certificates.cert-manager.io 2023-01-10T06:31:19Z -challenges.acme.cert-manager.io 2023-01-10T06:31:19Z -clusterissuers.cert-manager.io 2023-01-10T06:31:19Z -devicerollouts.kuesta.hrk091.dev 2023-01-10T06:43:30Z -gitrepositories.source.toolkit.fluxcd.io 2023-01-10T06:31:20Z -helmcharts.source.toolkit.fluxcd.io 2023-01-10T06:31:20Z -helmrepositories.source.toolkit.fluxcd.io 2023-01-10T06:31:20Z -issuers.cert-manager.io 2023-01-10T06:31:19Z -ocdemoes.kuesta.hrk091.dev 2023-01-10T06:43:36Z -ocirepositories.source.toolkit.fluxcd.io 2023-01-10T06:31:20Z -orders.acme.cert-manager.io 2023-01-10T06:31:19Z +git submodule update --init --recursive ``` -Some CRDs belonging to `kuesta.hrk091.dev`, `source.toolkit.fluxcd.io`, `cert-manager.io` are installed. - - -2: Pods: -```bash -kubectl get pods -A | grep -v 'kube-system' -``` +### Configuration of env file +Place the following env file in the K-SOT repository cloned above. +/.env ```bash -NAMESPACE NAME READY STATUS RESTARTS AGE -cert-manager cert-manager-7475574-t7qlm 1/1 Running 0 12m -cert-manager cert-manager-cainjector-d5dc6cd7f-wbh6r 1/1 Running 0 12m -cert-manager cert-manager-webhook-6868bd8b7-kc85s 1/1 Running 0 12m -device-operator-system device-operator-controller-manager-5d8648469b-57x4l 2/2 Running 0 11s -flux-system source-controller-7ff779586b-wsgf7 1/1 Running 0 12m -kuesta-getting-started gnmi-fake-oc01-79d4d679b4-tvm78 1/1 Running 0 10s -kuesta-getting-started gnmi-fake-oc02-69d9cc664d-56bsz 1/1 Running 0 10s -kuesta-getting-started subscriber-oc01 1/1 Running 0 9s -kuesta-getting-started subscriber-oc02 1/1 Running 0 9s -kuesta-system kuesta-aggregator-7586999c47-jj7m4 1/1 Running 0 27s -kuesta-system kuesta-server-85fc4f8646-kq72c 1/1 Running 0 27s -local-path-storage local-path-provisioner-9cd9bd544-lk9w9 1/1 Running 0 16m -provisioner-system provisioner-controller-manager-7675d487c8-w6f7x 1/2 Running 0 17s +KIND_NAME=ksot-started +GITHUB_REPO_URL=https://{GithubUserName}:{GithubUserToken}@github.com/{GithubUserName}/ksot-example +GITHUB_USER_NAME={GithubUserName} +GITHUB_USER_MAIL={GithubMailAddress} ``` -When all pods show Running status, you are ready to continue. - -Kuesta core services are deployed in the following namespaces: - -- kuesta-system - - Kuesta Server which provides core features and serves API. -- provisioner-system - - Kubernetes custom operator used for GitOps and multi-device transaction management. -- flux-system - - Flux source-controller and Custom Resources to integrate with manifest sources. -- cert-manager - - Act as a private CA and issue certificates for mTLS. - -The resources for this getting-started are deployed as well in the following namespaces: - -- device-operator-system - - Kubernetes custom operator as a device driver to configure device emulator. -- kuesta-getting-started - - Device emulators for this getting started, and Kubernetes custom resources to trigger device configuration. - -Following 2 pods are device emulators which can be configured by OpenConfig over gNMI, named `oc01` and `oc02`. - +/github-server/config/overlays/test/.env ```bash -kuesta-getting-started gnmi-fake-oc01-79d4d679b4-tvm78 1/1 Running 0 10s -kuesta-getting-started gnmi-fake-oc02-69d9cc664d-56bsz 1/1 Running 0 10s +GITHUB_REPO_URL=https://{GithubUserName}:{GithubUserToken}@github.com/{GithubUserName}/ksot-example ``` -If you want to check what configurations are stored in these emulators, you can easily do it -by port-forwarding and requesting to these emulator pods as follows: - -```bash -# Get oc01 emulator's configuration -kubectl -n kuesta-getting-started port-forward svc/gnmi-fake-oc01 9339:9339 -gnmic -a :9339 -u admin -p admin get --path "" --encoding JSON --skip-verify +### Configuration of the YANG +#### YANG settings for equipment +Acquire all YANG in [YANG Folder]( https://github.com/opennetworkinglab/ODTN-emulator/tree/master/emulator-oc-cassini/yang/openconfig-odtn) of [ODTN-emulator](https://github.com/opennetworkinglab/ODTN-emulator), which is the device to be managed in this article. Create a folder (name: cassini) under ```nb-server/pkg/tf/yang/devices`` and place the YANG files you just acquired. +#### Setting up YANG for services +Create a folder (name: transceivers) under ``nb-server/pkg/tf/yang/devices`` and place the yang files with the following contents in it. + +```yang +module transceivers { + namespace "tf-ksot/transceivers"; + prefix ts; + grouping transceivers-top { + list transceivers { + key "name"; + leaf name { + type string; + } + leaf-list up { + type string; + } + leaf-list down { + type string; + } + } + } + uses transceivers-top; +} ``` - -## Request Service configuration and run GitOps - -A **Service** is a abstracted high-level model of the network configuration, and you can configure multiple devices -by creating/updating Services. - -In the sample repository there is a sample Service named `oc-circuit`, you can try it as a demonstration. -Service is written by CUE. For example, `oc-circuit` service is as follows: - -```cue -package oc_circuit +### Configuration of equipment configuration derivation package +```nb-server/pkg/tf/transceivers.go```with the following contents. +```go +package tf import ( - ocdemo "github.com/hrk091/kuesta-testdata/pkg/ocdemo" + "encoding/json" + "fmt" + + "github.com/nttcom-ic/ksot/nb-server/pkg/model/pathmap" ) -#Input: { - // kuesta:"key=1" - vlanID: uint32 - endpoints: [...{ - device: string - port: uint32 - }] +type Transceiver struct { + Name string `json:"name"` + Nos string `json:"nos"` + Up []string `json:"up"` + Down []string `json:"down"` } +type Transceivers map[string][]Transceiver -#Template: { - input: #Input - - output: devices: { - for _, ep in input.endpoints { - "\(ep.device)": config: { - ocdemo.#Device - - let _portName = "Ethernet\(ep.port)" - Interface: "\(_portName)": SubInterface: "\(input.vlanID)": { - Ifindex: ep.port - Index: input.vlanID - Name: "\(_portName).\(input.vlanID)" - AdminStatus: 1 - OperStatus: 1 +func TfTransceivers(ts interface{}) (map[string]pathmap.PathMapInterface, error) { + fmt.Println("hello") + mapByte, err := json.Marshal(ts) + if err != nil { + return nil, err + } + var transceivers Transceivers + if err := json.Unmarshal(mapByte, &transceivers); err != nil { + fmt.Println(err) + return nil, err + } + results := make(map[string]pathmap.PathMapInterface) + fmt.Println("tflogic: ", transceivers) + for _, devices := range transceivers { + for _, device := range devices { + result, err := pathmap.NewPathMap(map[string]interface{}{}) + if err != nil { + return nil, err + } + for _, v := range device.Up { + path := fmt.Sprintf("/openconfig-platform:components/component[name=%v]/openconfig-platform-transceiver:transceiver/config/enabled", v) + err = result.SetValue(path, true, map[string]string{}) + if err != nil { + return nil, err } - - Vlan: "\(input.vlanID)": { - VlanId: input.vlanID - Name: "VLAN\(input.vlanID)" - Status: ocdemo.#Vlan_Status_ACTIVE - Tpid: ocdemo.#OpenconfigVlanTypes_TPID_TYPES_UNSET + } + for _, v := range device.Down { + path := fmt.Sprintf("/openconfig-platform:components/component[name=%v]/openconfig-platform-transceiver:transceiver/config/enabled", v) + err = result.SetValue(path, false, map[string]string{}) + if err != nil { + return nil, err } } + results[device.Name] = result } } + fmt.Println("check: ", results) + return results, nil } ``` +```nb-server/pkg/tf/tf.go``` to the following content. +```go +package tf -The `oc-circuit` Service will conduct mapping from `#Template.input` (Service config) to the `#Template.output` (multiple network device configs) as defined in `#Template`, then it will generate simple vlan and vlan sub-interface configurations. -To use `oc-circuit` Service, you need to provide vlanID and multiple device ports according to the `#Input` type definition. - -You can create the `oc-circuit` Service by the following steps: - -1: Create a request json file named `oc-circuit-vlan100.json` with the following content: +import ( + "github.com/nttcom-ic/ksot/nb-server/pkg/model" +) -```json -{ - "vlanID": 100, - "endpoints": [ - { - "device": "oc01", - "port": 1 - }, - { - "device": "oc02", - "port": 1 - } - ] -} -``` -When using the http interface, please create the following JSON instead of the above JSON. (Specify the path of the service in "path" and the value of the service to be submitted in "value.) +var TfLogic = model.NewPathMapLogic() -```json -{ - "path": "/services/oc_circuit/100", - "value": { - "vlanID": 100, - "endpoints": [ - { - "device": "oc01", - "port": 1 - }, - { - "device": "oc02", - "port": 1 - } - ] - } +func init() { + // User needs to create a function to generate a pathmap and add it to the MAP. + // Example. + // TfLogic["serviceName"] = serviceName + TfLogic["transceivers"] = TfTransceivers } ``` -This sample Service requests both oc01 and oc02 device emulators to create a VLAN sub-interface with vlanID=100 on port 1. - -2: Port-forward to the kuesta-server Pod running on your local Kubernetes. - +## 4. Start up the device emulator +Add an env file with emulator connection information. +/sb-server/config/overlays/test/.env ```bash -kubectl -n kuesta-system port-forward svc/kuesta-server 9339:9339 +cassini=root ``` -If the http interface is used, the following is the case. - +Launch [OTDN-emulator](https://github.com/opennetworkinglab/ODTN-emulator) with the following command. ```bash -kubectl -n kuesta-system port-forward svc/kuesta-server 8080:8080 +docker pull onosproject/oc-cassini:0.21 +docker run -it -d --name odtn-emulator_openconfig_cassini_1 -p 11002:830 onosproject/oc-cassini:0.21 ``` -3: Send gNMI set request to kuesta-server using `gnmic`. - +Make sure the container is up and running as follows. ```bash -gnmic -a :9339 -u dummy -p dummy set --replace-path "/services/service[kind=oc_circuit][vlanID=100]" --encoding JSON --insecure --replace-file oc-circuit-vlan100.json +% docker ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +52da5c9f1c79 onosproject/oc-cassini:0.21 "sh /root/script/pus…" 4 hours ago Up 4 hours 22/tcp, 8080/tcp, 0.0.0.0:11002->830/tcp odtn-emulator_openconfig_cassini_1 ``` -If you use the http interface, send the following POST Request to the Questa server using `curl`. -```bash -curl -X POST -H "Content-Type: application/json" -d @oc-circuit-vlan100.json http://localhost:8080/set +Create ```sb-server/connect.json``` in the K-SOT repository to add connection information from the controller to [OTDN-emulator](https://github.com/opennetworkinglab/ODTN-emulator) and save it with the following contents. +```json +{ + "cassini": { + "ip": "host.docker.internal", + "port": 11002, + "username": "root", + "hostKeyVerify": false, + "if": "netconf" + } +} ``` -4: Check the PullRequest(PR) in your configuration repository on GitHub web console. Access [PR list](https://github.com///pulls) then you will find the PR which titles as `[kuesta] Automated PR`. You can see what services and devices are configured by this PR on the PR comment, and their details from the `Files changed` tab. - -5: Before merging PR branch, it is better to monitor `DeviceRollout` resource, which conducts a device configuration rollout. Run monitor with `kubectl`: - +## 5. Deploy K-SOT +Execute the following command in the root of the K-SOT repository. ```bash -kubectl -n kuesta-getting-started get devicerollouts.kuesta.hrk091.dev -w +make getting-started ``` - -If you see there is one `DeviceRollout` resource and its `STATUS` is `Completed`, you are ready to run GitOps delivery procedure. +After execution, check the pods running with ```kubectl get pod`` and you will see the following three pods have been created. ```bash -NAME PHASE STATUS -kuesta-testdata Healthy Completed +NAMESPACE NAME READY STATUS RESTARTS AGE +default ksot-github-deployment-766b6ff499-72zkr 1/1 Running 0 24s +default ksot-nb-deployment-967757888-dqzw7 1/1 Running 0 24s +default ksot-sb-deployment-6d89c6f85c-zksl5 1/1 Running 0 24s +... ``` - -6: Merge the PR on GitHub web console, and go to the terminal where `DeviceRollout` monitor running. -In one minute, you will see `DeviceRollout` status changes to `Running`, then changes back to `Completed` again. +## 6. Operation check +### Implementing port-forwarding +First, port-forwarding should be performed on the k8s service that will be the Northbound. ```bash -NAME PHASE STATUS -kuesta-testdata Healthy Completed -kuesta-testdata Healthy Completed -kuesta-testdata Healthy Running -kuesta-testdata Healthy Running -kuesta-testdata Healthy Running -kuesta-testdata Healthy Completed +kubectl port-forward svc/ksot-nb-service 8080:8080 ``` -7: Check the updated device configuration. Get entire device config by sending gNMI get request to kuesta-server with `gnmic`: - -```bash -gnmic -a :9339 -u admin -p admin get --path "/devices/device[name=oc01]" --path "/devices/device[name=oc02]" --encoding JSON --insecure -``` +### Get equipment information. +Perform ```PUT: http://localhost:8080/sync/devices``` to reflect the current device configuration in the Github repository. +It is successful if the following files are created in ``Devices/cassini`` of the Github repository for verification. +- actual.json: configuration obtained from the actual device +- ref.json: parameters set from each service (default value is empty JSON) +- set.json: settings submitted by the controller (initial values are the same as those obtained from the actual device) -If you use the http interface, send the following POST Request to the Questa server using `curl`. -```bash -curl -X POST -H "Content-Type: application/json" -d '{"paths": ["/devices/oc01", "/devices/oc02"]}' http://localhost:8080/get +### Service Creation +```POST: http://localhost:8080/services``` is executed with the following JSON as the body, the service specified in the body is created, and the device settings are changed. +```JSON +{ + "transceivers": { + "transceivers:transceivers": [ + { + "name": "cassini", + "up": [], + "down": [ + "oe1", + "oe2", + ] + } + ] + } +} ``` - -The output displays the gNMI response payload like: - -```json -[ - { - "source": ":9339", - "timestamp": 1673360105000000000, - "time": "2023-01-10T23:15:05+09:00", - "updates": [ - { - "Path": "devices/device[name=oc01]", - "values": { - "devices/device": { - "Interface": { - "Ethernet1": { - "AdminStatus": 1, - "Description": "awesome interface!!", - "Enabled": false, - "Mtu": 9000, - "Name": "Ethernet1", - "OperStatus": 1, - "Subinterface": { - "100": { - "AdminStatus": 1, - "Ifindex": 1, - "Index": 100, - "Name": "Ethernet1.100", - "OperStatus": 1 - }, - ... - }, - ... - }, - ... - }, - "Vlan": { - "100": { - "Member": [], - "Name": "VLAN100", - "Status": 1, - "Tpid": 0, - "VlanId": 100 - }, - ... +Make sure the following files are created in ``Services/transceivers`` in the verification Github repository. +- input.json: the value of the submitted service +- output.json: xpath and corresponding values for the device whose configuration you have changed + +### Get equipment information (after service creation) +Perform ```PUT: http://localhost:8080/sync/devices``` to reflect the current device configuration in the Github repository. +The ``Devices/cassini/actual.json`` in the Github repository for verification is updated as follows, and the transceivers in the specified location of [OTDN-emulator](https://github.com/opennetworkinglab/ODTN-emulator) are down. The ``Devices/cassini/actual.json`` is updated as follows. +```diff +{ +... + "name": "oe1", + "config": { + "name": "oe1" + }, + "state": { + "type": "openconfig-platform-types:TRANSCEIVER", + "empty": false + }, + "openconfig-platform-transceiver:transceiver": { + "config": { + - "enabled": true, + + "enabled": false, + "form-factor-preconf": "openconfig-transport-types:CFP2_ACO" + } + } +... + "name": "oe2", + "config": { + "name": "oe2" + }, + "state": { + "type": "openconfig-platform-types:TRANSCEIVER", + "empty": false + }, + "openconfig-platform-transceiver:transceiver": { + "config": { + - "enabled": true, + + "enabled": false + "form-factor-preconf": "openconfig-transport-types:CFP2_ACO" + } + } +... +} ``` -The response when using the http interface is as follows. -```json -[ - { - "Interface": { - "Ethernet1": { - "AdminStatus": 1, - "Description": "", - "Enabled": false, - "Mtu": 9000, - "Name": "Ethernet1", - "OperStatus": 1, - "SubInterface": { - "100": { - "AdminStatus": 1, - "Ifindex": 1, - "Index": 100, - "Name": "Ethernet1.100", - "OperStatus": 1 - } - }, - "Subinterface": {}, - "Type": 80 - }, - "Ethernet2": { - "AdminStatus": 1, - "Description": "", - "Enabled": false, - "Mtu": 9000, - "Name": "Ethernet2", - "OperStatus": 1, - "Subinterface": {}, - "Type": 80 - }, - "Ethernet3": { - "AdminStatus": 1, - "Description": "", - "Enabled": false, - "Mtu": 9000, - "Name": "Ethernet3", - "OperStatus": 1, - "Subinterface": {}, - "Type": 80 - } - }, - "Vlan": { - "100": { - "Member": [], - "Name": "VLAN100", - "Status": 1, - "Tpid": 0, - "VlanId": 100 - } - } - }, - { - "Interface": { - "Ethernet1": { - "AdminStatus": 1, - "Description": "", - "Enabled": false, - "Mtu": 9000, - "Name": "Ethernet1", - "OperStatus": 1, - "SubInterface": { - "100": { - "AdminStatus": 1, - "Ifindex": 1, - "Index": 100, - "Name": "Ethernet1.100", - "OperStatus": 1 - } - }, - "Subinterface": {}, - "Type": 80 - }, - "Ethernet2": { - "AdminStatus": 1, - "Description": "", - "Enabled": false, - "Mtu": 9000, - "Name": "Ethernet2", - "OperStatus": 1, - "Subinterface": {}, - "Type": 80 - }, - "Ethernet3": { - "AdminStatus": 1, - "Description": "", - "Enabled": false, - "Mtu": 9000, - "Name": "Ethernet3", - "OperStatus": 1, - "Subinterface": {}, - "Type": 80 - } - }, - "Vlan": { - "100": { - "Member": [], - "Name": "VLAN100", - "Status": 1, - "Tpid": 0, - "VlanId": 100 +### Updating services +Execute ``PUT: http://localhost:8080/services`` with the following JSON as the body, update the service specified in the body, and change the device settings. +In this case, we will update the oe1 transceiver. +```JSON +{ + "transceivers": { + "transceivers:transceivers": [ + { + "name": "cassini", + "up": [ + "oe1", + ], + "down": [ + "oe2", + ] } - } + ] } -] +} ``` -You will find that vlan and vlan sub-interfaces of both devices oc01 and oc02 are configured correctly as implemented in the `oc-circuit` service model. -In addition, these device config changes are committed and pushed to your status repository, you can find these device config updates from the main branch head. - - -## Clean up +### Get equipment information (after service update) +Perform ```PUT: http://localhost:8080/sync/devices``` to reflect the current equipment configuration in the Github repository. +The ```Devices/cassini/actual.json``` in the Github repository for verification is updated as follows, and the transceivers in the specified location of [OTDN-emulator](https://github.com/opennetworkinglab/ODTN-emulator) are updated. The ```Devices/cassini/actual.json``` is updated as follows +```diff +{ +... + "name": "oe1", + "config": { + "name": "oe1" + }, + "state": { + "type": "openconfig-platform-types:TRANSCEIVER", + "empty": false + }, + "openconfig-platform-transceiver:transceiver": { + "config": { + + "enabled": true, + - "enabled": false, + "form-factor-preconf": "openconfig-transport-types:CFP2_ACO" + } + } +... +} +``` -To delete the local cluster you created for this getting-started, just run: +### delete service. +```DELETE: http://localhost:8080/services?name=transceivers```. Delete the service with the name specified in the query parameters and change the configuration of the device. +Check the ``Services/transceivers`` folder in the verification Github repository as it will disappear. -```bash -kind delete cluster +### Get device information (after deleting the service) +Perform ```PUT: http://localhost:8080/sync/devices``` to reflect the current equipment configuration in the Github repository. +The ```Devices/cassini/actual.json``` in the Github repository for verification will be updated as follows, and you will see that the configuration points that were submitted from the service will disappear. +```diff +{ +... + "name": "oe1", + "config": { + "name": "oe1" + }, + "state": { + "type": "openconfig-platform-types:TRANSCEIVER", + "empty": false + }, + "openconfig-platform-transceiver:transceiver": { + "config": { + - "enabled": true, + "form-factor-preconf": "openconfig-transport-types:CFP2_ACO" + } + } +... + "name": "oe2", + "config": { + "name": "oe2" + }, + "state": { + "type": "openconfig-platform-types:TRANSCEIVER", + "empty": false + }, + "openconfig-platform-transceiver:transceiver": { + "config": { + - "enabled": false + "form-factor-preconf": "openconfig-transport-types:CFP2_ACO" + } + } +... +} ``` -Do not forget to remove your PAT to access your private repository if no longer needed. +### External tools used in this section +- [OTDN-emulator](https://github.com/opennetworkinglab/ODTN-emulator) \ No newline at end of file diff --git a/content/en/docs/Guides/_index.md b/content/en/docs/Guides/_index.md deleted file mode 100755 index 46766e5..0000000 --- a/content/en/docs/Guides/_index.md +++ /dev/null @@ -1,13 +0,0 @@ - ---- -title: "Guides" -linkTitle: "Guides" -weight: 4 -date: 2017-01-04 -description: > - Guides to help you complete a specific goal. ---- - -{{% pageinfo %}} -Work in progress. -{{% /pageinfo %}} diff --git a/content/en/docs/Installation/_index.md b/content/en/docs/Installation/_index.md deleted file mode 100644 index 5f06684..0000000 --- a/content/en/docs/Installation/_index.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -title: "Installation" -linkTitle: "Installation" -weight: 2 -description: > - Instructions to install Kuesta components. ---- - -Information in this section helps you to install Kuesta to your Kubernetes cluster. - -## Before you begin - -You must have a Kubernetes cluster running version 1.24 or later. - -If you don’t have a cluster, you can create local one for testing with kind. -[Install kind](https://kind.sigs.k8s.io/docs/user/quick-start/) and create a cluster by running `kind create cluster`. -This will create a cluster running locally, with RBAC enabled and your user granted the cluster-admin role. - - -## Prerequisites - -1. [Install kubectl](https://kubernetes.io/docs/tasks/tools/) to run commands against Kubernetes clusters. -2. [Install cue](https://cuelang.org/docs/install/) to run Kuesta installation script. - - -## Installing Kuesta on Kubernetes - -To install Kuesta components, just run cue script: - -```bash -git clone https://github.com/nttcom/kuesta.git -cd kuesta/tool/install -cue install -``` - -If you want to install a specific release version or install from the other container image registry, use `version` and `imageRegistry` tag: - -```bash -cue -t imageRegistry= -t version= install -``` - -Provide required parameters according to the instructions: - -```bash -GitHub repository for config: https://github.com// -GitHub repository for status: https://github.com// -GitHub username: -GitHub private access token: -Are these git repositories private? (yes|no): yes -Do you need sample driver and emulator for trial?: (yes|no) yes - ---- -GitHub Config Repository: https://github.com// -GitHub Status Repository: https://github.com// -GitHub Username: -GitHub Access Token: *** -Use Private Repo: true - -Image Registry: ghcr.io/nttcom/kuesta -Version: latest -Deploy sample driver and emulator: true ---- - -Continue? (yes|no) yes -``` - -For Kuesta to perform git-push and create pull-request, you need to prepare a GitHub [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) (PAT) and provide it in the installation. -PAT provided here is stored in a Secret named `kuesta-system/kuesta-secrets` for kuesta-server to operator git clone, pull, push and create PullRequest. - -You can also use this PAT when you set up `GitRepository` to watch your private repository via Git over HTTPS, to grant Flux source-controller to conduct git operations with your private repository. - - -## Configuring GitOps with Flux source-controller - -To set up GitOps using Flux source-controller, you need to create `GitRepository` to define the IaC manifest source. -The following is the example of a `GitRepository`, that is created in the [getting-started](/docs/getting-started) tutorial. - -```yaml -apiVersion: source.toolkit.fluxcd.io/v1beta2 -kind: GitRepository -metadata: - name: kuesta-testdata - namespace: kuesta-getting-started -spec: - interval: 1m0s - url: https://github.com/hrk091/kuesta-testdata - ref: - branch: main - secretRef: - name: kuesta-testdata-secret - timeout: 60s -``` - -You can get more detail from [the FluxCD documentation](https://fluxcd.io/flux/components/source/gitrepositories/). - -In Kuesta, once you create the `GitRepository`, Kuesta's source-watcher controller detects it and creates the corresponding `DeviceRollout`. -`DeviceRollout` is a custom resource responsible for multi-device transaction management. The `DeviceRollout` created in the getting-started tutorial is as follows: - -``` -apiVersion: kuesta.hrk091.dev/v1alpha1 -kind: DeviceRollout -metadata: - name: kuesta-testdata - namespace: kuesta-getting-started -spec: - deviceConfigMap: - oc01: - checksum: 1524caf17ec4c133f6f275326a6c9742a0155007f8eaa28ea601ce7ac39c0566 - gitRevision: main/30746f9beb48d237b6c0e0357708b3ed1f95cd1b - oc02: - checksum: 0b03381195ba613e0dd20e5d2683711e9d6082f0634bee7c54014de2eadf0fc9 - gitRevision: main/30746f9beb48d237b6c0e0357708b3ed1f95cd1b -status: - desiredDeviceConfigMap: - oc01: - checksum: 1524caf17ec4c133f6f275326a6c9742a0155007f8eaa28ea601ce7ac39c0566 - gitRevision: main/30746f9beb48d237b6c0e0357708b3ed1f95cd1b - oc02: - checksum: 0b03381195ba613e0dd20e5d2683711e9d6082f0634bee7c54014de2eadf0fc9 - gitRevision: main/30746f9beb48d237b6c0e0357708b3ed1f95cd1b - deviceStatusMap: - oc01: Completed - oc02: Completed - phase: Healthy - status: Completed -``` - -The lifecycle of `DeviceRollout` resource is completely automated, you don't need to touch it at all. - - -## Installing Device Driver and configuring Device Custom Resource - -{{% pageinfo %}} - -The following instructions are just for the sample Kubernetes Custom Operator that is used in the getting-started tutorial. -The details will be different depending on the target devices you want to configure by Kuesta and your Kubernetes custom operator to configure them. - -{{% /pageinfo %}} - -To configure the devices which supports OpenConfig over gNMI, you can use the sample Kubernetes custom operator developed at [kuesta/device-operator](https://github.com/nttcom/kuesta/tree/main/device-operator). This sample Kubernetes custom operator is specialized -to configure OpenConfig devices which support [basic YANG sets](https://github.com/nttcom/kuesta/tree/main/device-operator/pkg/model/yang), -you can extend this custom operator by adding any YANG modules which is written in [OpenConfig style](https://github.com/openconfig/public/blob/master/doc/openconfig_style_guide.md). - - -You can install this sample Kubernetes custom operator either using `make` command or using `kubectl/kustomize` directly, -but the fastest way is using the Kuesta installation script. It uses `kustomize` internally by creating kustomize overlay directory named `getting-started`, you can start with it to customize your setup. - -To install the sample Kubernetes custom operator using `getting-started` overlay directory, run the following: - -```bash -export IMG=ghcr.io/nttcom/kuesta/device-operator:latest -export KUSTOMIZE_ROOT=overlays/getting-started -make deploy -``` - -To configure devices from Kuesta, you also need to create custom resources for each device in addition to the Kubernetes custom operator. -In the getting-started tutorial, following `OcDemo` custom resource is created for oc01 gNMI emulator. - -```yaml -apiVersion: kuesta.hrk091.dev/v1alpha1 -kind: OcDemo -metadata: - name: oc01 - namespace: kuesta-getting-started -spec: - address: gnmi-fake-oc01.kuesta-getting-started - port: 9339 - rolloutRef: kuesta-testdata - tls: - secretName: oc01-cert - skipVerify: true -``` - -`OcDemo` defines a connection parameters to access the configuration target device, address, port, username/password, and TLS settings. -`.spec.rolloutRef` is also a required field to specify `DeviceRollout` to subscribe to the device configuration changes given by Flux source-controller GitOps. -For more information, run `kubectl explain ocdemo.spec`. diff --git a/content/en/docs/Reference/_index.md b/content/en/docs/Reference/_index.md index de08e4f..91cc691 100644 --- a/content/en/docs/Reference/_index.md +++ b/content/en/docs/Reference/_index.md @@ -3,22 +3,14 @@ title: "Reference" linkTitle: "Reference" weight: 6 description: > - Further documentation on Kuesta. + Further documentation on K-SOT. --- -- CUE - - [cuelang.org](https://cuelang.org/docs/) - - [Cuetorial](https://cuetorials.com/) -- FluxCD - - [gitops-toolkit](https://fluxcd.io/flux/gitops-toolkit/) - - [source-controller](https://fluxcd.io/flux/components/source/) - - [source-watcher](https://fluxcd.io/flux/gitops-toolkit/source-watcher/) -- Kubernetes Custom Operator - - [kubebuilder](https://book.kubebuilder.io/) -- OpenConfig - - [YANG models](https://github.com/openconfig/public/tree/master/release/models) - - [OpenConfig Style](https://github.com/openconfig/public/blob/master/doc/openconfig_style_guide.md) -- ygot (YANG Go Tools) - - [Example of go struct generation](https://github.com/openconfig/ygot/tree/master/demo/getting_started) -- gNMI - - [Specification](https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-specification.md) +- Kubernetes + - [document](https://kubernetes.io/ja/) +- Go + - [document](https://go.dev/) +- YANG + - [RFC6020](https://datatracker.ietf.org/doc/html/rfc6020) +- NETCONF + - [RFC4741](https://datatracker.ietf.org/doc/html/rfc4741) diff --git a/content/en/docs/_index.md b/content/en/docs/_index.md index 4968bc1..baeceaf 100755 --- a/content/en/docs/_index.md +++ b/content/en/docs/_index.md @@ -8,6 +8,6 @@ menu: weight: 10 --- -Kuesta is a cloud-native network configuration framework, enabling operators Infrastructure-as-Code of network equipments. It consists of CUE-based data mapper and some Kubernetes custom operators for GitOps, and provides us a rich network abstraction and automation. +K-SOT is a cloud-native network configuration framework, enabling operators Infrastructure-as-Code of network equipments. It consists of CUE-based data mapper and some Kubernetes custom operators for GitOps, and provides us a rich network abstraction and automation. diff --git a/content/ja/_index.html b/content/ja/_index.html index c6aeeef..0867777 100644 --- a/content/ja/_index.html +++ b/content/ja/_index.html @@ -1,21 +1,18 @@ +++ -title = "Kuesta" -linkTitle = "Kuesta" +title = "K-SOT" +linkTitle = "K-SOT" +++ {{< blocks/cover title="" subtitle="" image_anchor="top" color="dark" >}}
- Kuesta -
-
- CUE-based Network IaC on Kubernetes + K-SOT
}}"> ドキュメント - + ダウンロード
@@ -23,7 +20,7 @@ {{% blocks/lead color="white" %}} -**Kuesta**は、ネットワークのInfrastructure as Codeを可能にするオープンソースのフレームワークです。
+**K-SOT**は、ネットワークのInfrastructure as Codeを可能にするオープンソースのフレームワークです。
クラウドネイティブなソフトウェア開発で培われたIaCやGitOpsのプラクティスをネットワークに適用し、
高度なネットワーク設定の自動化を実現します。 diff --git a/content/ja/docs/CLI/_index.md b/content/ja/docs/CLI/_index.md deleted file mode 100644 index 66bc2ce..0000000 --- a/content/ja/docs/CLI/_index.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: "CLI" -linkTitle: "CLI" -weight: 5 -description: > - kuesta CLIの使い方 ---- - -Kuestaでは、コンフィグIaCを更新する方式として、kuesta-serverを使ってAPI経由で更新する方式と `kuesta` CLIを用いる方式をサポートしています。 -`kuesta` CLIは、 Kuestaを用いつつも手動でコンフィグレポジトリの管理をしたい場合や、GitHub ActionsやGitHub Appsなどと連携してCIを構成する場合に役立ちます。 - - -## インストール - -Kuestaのtarファイルを、 [kuesta Releases page](https://github.com/nttcom/kuesta/releases) からダウンロードしてください。 -ダウンロードできたら展開して、PATHが通っているディレクトリに実行バイナリを配置してください。 - -```bash -# Replace YOUR-DOWNLOADED-FILE with the file path of your own. -sudo tar xvzf YOUR-DOWNLOADED-FILE -C /usr/local/bin/ kuesta -``` - -### ソースコードからビルド - -`kuesta` CLIをソースコードからビルドしたい場合は、Go1.18以上を用いた開発環境をセットアップしたのち、以下のコマンドを実行してください。 - -```bash -git clone https://github.com/nttcom/kuesta.git -cd kuesta -go build -o kuesta main.go -``` - -その後、ビルドされたバイナリをPATHが通っているディレクトリに配置してください。 - - -## 使い方 - -kuesta-serverを使用せずに、`kuesta` CLIを用いてコンフィグIaCを更新するには、以下のステップを実行してください。 - -1: ネットワークコンフィグを管理しているGitHubマニフェストレポジトリを、クローンしてください。 - -2: Serviceコンフィグを更新してください。 - -3: 更新したServiceに `git add` を実行し、インデックスに追加してください。 - -4: Serviceコンフィグからネットワーク装置のコンフィグに変換するために、 `kuesta service apply` を以下の通り実行してください。 - -```bash -kuesta service apply -p= -``` - -Serviceコンフィグからネットワーク装置へのコンフィグ変換は、インデックスに追加されているServiceに限定して実行されます。 -インデックスに追加されていないServiceの変更は全てスキップされます。 - - -5: GitHubマニフェストレポジトリ上でプルリクエストを作成するために、 `kuesta git commit` を以下の通り実行してください。 -もしgitプロバイダへの認証が必要な場合は、コマンドラインオプション `--git-token` か `KUESTA_GIT_TOKEN` を用いて、認証済のアクセストークンを指定してください。 - - -```bash -kuesta git commit -p -r -``` - -その他の利用可能なコマンドや、コマンドラインオプションに関するより詳細な情報が知りたい場合は、 `kuesta help` を実行してください。 diff --git a/content/ja/docs/Concepts/_index.md b/content/ja/docs/Concepts/_index.md index 3d9c704..92909e4 100644 --- a/content/ja/docs/Concepts/_index.md +++ b/content/ja/docs/Concepts/_index.md @@ -3,60 +3,27 @@ title: "Concepts" linkTitle: "Concepts" weight: 3 description: > - Kuestaのコンセプト、アーキテクチャ、その他の技術関連情報について + K-SOTのコンセプト、アーキテクチャ、その他の技術関連情報について --- -## CUEを用いた Network Configuration as Code +## Goを用いた Network Configuration as Code -Kuestaは、複雑なネットワーク装置のコンフィグを抽象化し、ユーザのインテントを簡単に記述できる高レベルのデータモデルとAPIを公開することをサポートします。ネットワーク装置のデータモデルは、数多のネットワーキング機能を提供するために詳細かつ複雑であり、Infrastructure as Codeのリソースモデルとして扱うには適していません。ユーザのインテントを簡単に表現できるデータモデルを提供するためには、複雑さを隠蔽しわかりやすく抽象化した高レベルなデータモデルが必要です。加えて、E2E接続のようなドメイン全体を抽象化したモデルを実現するには、複数のネットワーク装置をまたいで設定を行うデータモデルが必要になります。 +K-SOTは、複雑なネットワーク装置のコンフィグを抽象化し、ユーザのインテントを簡単に記述できる高レベルのデータモデルとAPIを公開することをサポートします。ネットワーク装置のデータモデルは、数多のネットワーキング機能を提供するために詳細かつ複雑であり、Infrastructure as Codeのリソースモデルとして扱うには適していません。ユーザのインテントを簡単に表現できるデータモデルを提供するためには、複雑さを隠蔽しわかりやすく抽象化した高レベルなデータモデルが必要です。加えて、E2E接続のようなドメイン全体を抽象化したモデルを実現するには、複数のネットワーク装置をまたいで設定を行うデータモデルが必要になります。 このような上位モデルへの抽象化を行うと、上位モデルから低レベルな装置コンフィグへのデータマッピングは非常に複雑になります。 上位モデルと下位モデルは多対多の関係性を持つため、データマッピングに加えてデータの合成も同時に行う必要があります。このとき、データの欠損や競合、データ制約違反を起こさないように配慮しなければなりません。 Python/Jinjaを用いたシンプルなテキストテンプレートのアプローチでは、この複雑な問題を解くのは困難です。 -Kuestaでは、上位モデルから下位モデルへのデータマッピングロジックを記述するプログラミング言語として[CUE](https://github.com/cue-lang/cue) を採用しています。 -CUEは、データの合成と検証に強みを持つコンフィグ記述言語であり、次のような理由から上記のユースケースに適しています。 -- CUEは、複数のドキュメントツリーを任意の階層で統一することを可能にします。CUEは、交換律と結合律を満たし、冪等な演算が可能という特徴があり、データを合成する順序によらず、必ず同じ結果になるように設計されています。 -- CUEは、型と値を同一のものとして扱います。型とデータ制約も値の一種であり、両者の違いは具体的な値を持つか否かだけです。この新しいアプローチにより、コンフィグを記述するのと同時にスキーマとデータ制約と記述でき、シンプルかつ効率的に扱えます。 -- CUEは高いプログラマビリティを有しており、テンプレート化やモジュール化といったソフトウェアコーディングのプラクティスをサポートしています。汎用的な言語を使うのと同じようなメリットが得られます。 +K-SOTでは、上位モデルから下位モデルへのデータマッピングロジックをGoで記述できます。また、データの合成についてはユーザーが意識せずに実装することができます。 -CUEの詳細についてより知りたければ、["cuelang.org"](https://cuelang.org/docs/about/) を参照してください。 +## GitHubによるデータ管理 +K-SOTは、ネットワーク装置コンフィグのためのGitHubによるデータ管理を提供します。ネットワーク全体のコンフィグを宣言的に記述し、GitHubリポジトリでバージョン管理し、信頼できる唯一の情報源(Single Source of Truth: SSoT) とすることを目的としています。 -## GitOps +## K-SOTのコンポーネント -Kuestaは、ネットワーク装置コンフィグのためのGitOpsを提供します。ネットワーク全体のコンフィグを宣言的に記述し、Gitリポジトリでバージョン管理し、信頼できる唯一の情報源(Single Source of Truth: SSoT) とすることを目的としています。 -コンフィグ設定プロセスは完全に自動化されており、Gitリポジトリのバージョンを指定することで、そのバージョンのコンフィグがネットワーク装置に自動で設定されます。 -ネットワークの構成切り替えやロールバックをするには、GitブランチのHEADをデプロイしたいバージョンに変更するだけです。 +K-SOTは以下のコンポーネントから構成されています。 -Kuestaは、以下の理由からPullベースのアプローチを選択しています。 -- ネットワーク装置の設定が更新されるたびに、バージョン指定されたデプロイされるべき設定と、実際のネットワーク装置の設定との間のずれを検出するため。 -- SSoTのGitリポジトリに保存されているネットワーク全体のコンフィグが、あらかじめ整備されたデプロイパイプラインにより画一的に設定されることで、コンフィグの加工処理を挿入することなくネットワーク装置にデプロイされることを保証するため。 -- すべてのネットワーク装置のクレデンシャルが集約されることで設定システムの権限が過度に強力になり、セキュリティリスクが高まるのを避けるため。Kuestaではネットワーク装置のクレデンシャルはKubernetes Secretリソースとして保存されるため、ExternalSecrets OperatorなどのOSSツールを使ってパブリッククラウドのSecretManagerと統合し、セキュアにこれらのクレデンシャルを管理することができます。 - -GitOpsの詳細については、 ["What is GitOps?"](https://www.gitops.tech/#what-is-gitops) をご覧ください。 - - -## Kubernetesカスタムオペレータ - -Kuestaは、Infrastructure as Codeを実現するエンジンとして、Kubernetesの「Reconciliation loop」と「Operatorパターン」を使用しています。 -Kubernetesはコンテナのオーケストレーションツールとして有名ですが、あらゆる外部リソースのデプロイを自動化するために拡張することができます。ネットワーク装置も例外ではありません。 -Kuestaは、複数のKubernetesカスタムオペレータで構成されており、それぞれGitOpsを行うためのエンジン、マルチデバイス間の分散トランザクションコーディネータ、ネットワーク装置を設定するためのドライバなどの役割を担っています。 - -新しいベンダーのデバイスや新しいバージョンのネットワーク装置をKuestaでサポートしたい場合は、対応するKubernetesカスタムオペレータを開発することで実現できます。 - - -## Kuestaのコンポーネント - -Kuestaは以下のコンポーネントから構成されています。 - -- **kuesta-server** は、KuestaのコアとなるAPIサーバです。外部のサードパーティシステムと連携するためにgNMIを公開し、上位モデルから下位モデルへのデータマッピングとデータ合成を行い、GitOpsのために新しいGitコミットを作成やプルリクエストの発行などを行います。 - -- **kuesta-aggregator** は、ネットワーク装置の実際のコンフィグの変更を集約し、Gitコミットを作成して、設定変更の履歴をGitレポジトリに永続化します。 - -- **FluxCD source-controller** は、`GitRepository` Kubernetesカスタムリソースで指定されたGitリポジトリにおけるマニフェストの変更を検出します。 - -- **kuesta-provisioner** は、`gitrepository-watcher` コントローラと `DeviceRollout` Kubernetesカスタムリソースで構成されています。 `gitrepository-watcher` は `GitRepository` の状態を監視してマニフェストの変更を検出し、変更が検出されると `DeviceRollout` のステータスをランニングに更新し、ネットワーク装置のコンフィグ更新のトランザクションをトリガします。 - -Kuestaを使用してネットワーク装置に設定をするには、対象となるネットワーク装置に設定を行うためのKubernetesカスタムオペレータを独自に用意する必要があります。Kubernetesカスタムオペレータを開発する際は、強力なフレームワークである [kubebuilder](https://github.com/kubernetes-sigs/kubebuilder) を使用することがお勧めです。 -また、["Getting started"](/docs/getting-started) で使用した [device-operator](https://github.com/nttcom/kuesta/tree/main/device-operator) は、OpenConfig/gNMIデバイスを設定するために設計されたKubernetesカスタムオペレータのサンプルであり、これをベースに開発を始めることも可能です。この開発でもkubebuilderが使用されています。 +- **nb-server** はサービスモデルを受け取り、装置設定の導出を実施します。 +- **github-server** はGitHubの更新を行います。 +- **sb-server** は装置に設定を投入します。 diff --git a/content/ja/docs/Contribution guidelines/_index.md b/content/ja/docs/Contribution guidelines/_index.md deleted file mode 100644 index 1cbe302..0000000 --- a/content/ja/docs/Contribution guidelines/_index.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: "Contribution Guidelines" -linkTitle: "Contribution Guidelines" -weight: 10 -description: How to contribute to Kuesta ---- - -Kuesta is an open source project and we love getting patches and contributions to make Kuesta and its docs even better. - - -## Contributing to Kuesta - - -### Creating PullRequest - -All submissions, including submissions by project members, require review. We -use GitHub PullRequest for this purpose. Consult -[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more -information on using pull requests. - - -### Creating issues - -If you have found something that isn't working the way you'd expect, but you're not sure how to fix it yourself, please create an [issue](https://github.com/nttcom/kuesta/issues). - - -## How to run the test suites - -To run the whole test suites of all kuesta components: - -```bash -make test-all -``` - -To run the specified component test suites only, run the following at the top of the component dir: - -```bash -make test -``` - -For lint, install [golangci-lint](https://golangci-lint.run/usage/install/#local-installation) in advance, then run at the top of kuesta repo: - -```bash -make lint-all -``` - -If you want to run Kuesta locally, see ["Installtaion"](/docs/installation) page. diff --git a/content/ja/docs/Getting started/_index.md b/content/ja/docs/Getting started/_index.md index 6df481b..ecd93f6 100644 --- a/content/ja/docs/Getting started/_index.md +++ b/content/ja/docs/Getting started/_index.md @@ -3,32 +3,31 @@ title: "Getting Started" linkTitle: "Getting Started" weight: 1 description: > - Kuestaを動かしてみよう + K-SOTを動かしてみよう --- -このチュートリアルでは、以下のステップでKuestaを構築し、動作確認を行います。 - -1. ローカルのKubernetesクラスターを作成する -2. Kuestaをインストールする -3. 装置エミュレータを立ち上げる -4. 新しいServiceコンフィグを作成して、GitOpsを介して装置エミュレータに設定を投入する +このチュートリアルでは、以下のステップでK-SOTを構築し、動作確認を行います。 +1. ローカルKubernetesクラスタ作成 +2. 検証用のGithubレポジトリの作成 +3. K-SOTをインストール、各種ファイル設定 +4. 装置エミュレータを立ち上げる +5. K-SOTのデプロイ +6. 動作確認 ## 事前準備 -1. [golang (v1.20.4+))](https://go.dev/doc/install) をインストールしてください。カスタムコントローラーのツール類を使用するために必要です。 +1. [golang (v1.21.0+))](https://go.dev/doc/install) をインストールしてください。装置設定導出ロジックを書くのに必要です。 2. [docker (v20.10.24+)](https://docs.docker.com/engine/install) をインストールしてください。kindの実行に必要です。 3. [kind (v0.12.0+)](https://kind.sigs.k8s.io/docs/user/quick-start/) をインストールしてください。ローカルのKubernetesクラスタの構築に使用します。 4. [kubectl (v1.25.4+)](https://kubernetes.io/docs/tasks/tools/) をインストールしてください。Kubernetesクラスタに対してコマンドを実行する際に使用します。 -5. [cue (v0.4.x)](https://cuelang.org/docs/install/) をインストールしてください。Kuestaのインストールスクリプトの実行に必要です。 -6. [gnmic (v0.26.0+)](https://gnmic.kmrd.dev/install/) をインストールしてください。Kuestaサーバに対してgNMIリクエストを行うために必要です。 -## ローカルKubernetesクラスタの立ち上げ +## 1. ローカルKubernetesクラスタ作成 以下のコマンドを実行して、ローカルのKubernetesクラスタを立ち上げます。 ```bash -kind create cluster +kind create cluster --name ksot-started ``` 実行が完了したら、以下のコマンドを実行して、Kubernetesクラスタが正常に作成されたことを確認します。 @@ -47,473 +46,368 @@ To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'. ``` -## 検証用のGithubレポジトリの作成 - -KuestaのGitOpsを用いてネットワーク装置に設定を行うには、2つのGitHubレポジトリを作成する必要があります。 -1つ目はGitOpsの起点となるコンフィグ管理レポジトリで、2つ目はネットワーク装置の実際のコンフィグの変更履歴を管理するレポジトリです。 -[Kuesta Example](https://github.com/nttcom/kuesta-example) レポジトリをテンプレートとして使用することで、これらのレポジトリを簡単に作成できます。 -レポジトリ名は、小文字の英数字、'-'または'.'で構成され、英数字で始まり、英数字で終わる必要があります。 +## 2. 検証用のGithubレポジトリの作成 -以下を2回実行して、2つのGitHubレポジトリを作成してください。 +K-SOTをGithubを用いてネットワーク装置の設定を管理するには、GitHubレポジトリを作成する必要があります。 +[K-SOT Example](https://github.com/nttcom/ksot-example) レポジトリをテンプレートとして使用することで、これらのレポジトリを簡単に作成できます。 -1. [Kuesta Example](https://github.com/nttcom/kuesta-example) レポジトリの **Use this template** ボタンをクリックしてください。 +以下を実行して、GitHubレポジトリを作成してください。 -2. レポジトリ名を入力して、 **Create repository from template** ボタンをクリックしてください。レポジトリの公開・非公開については、好きな方を選択してください。 +1. [K-SOT Example](https://github.com/nttcom/ksot-example) レポジトリの **Use this template** ボタンをクリックしてください。 +2. レポジトリ名を入力して、 **Create repository from template** ボタンをクリックしてください。レポジトリの公開・非公開については、好きな方を選択してください。今回はレポジトリオーナーをユーザーのアカウントに設定し、レポジトリ名はksot-exampleと設定してください。 -## Kuestaと検証用サンプルリソースのインストール - -Kuestaと、検証用のドライバオペレータや装置エミュレータなどのサンプルリソースをインストールするには、以下のコマンドを実行してください。 +## 3. K-SOTをインストール、各種ファイル設定 +### K-SOTのレポジトリをclone、submoduleの初期化 +レポジトリのclone ```bash -git clone https://github.com/nttcom/kuesta.git -cd kuesta/tool/install -cue install +git clone https://github.com/nttcom/ksot.git ``` - -プロンプトが表示されますので、指示に従ってパラメータを入力してください。 -`GitHub repository for config` `GitHub repository for status`は前項で作成した２つの検証用のGithubレポジトリをそれぞれ指定してください。 - +submoduleの初期化 ```bash -GitHub repository for config: https://github.com// -GitHub repository for status: https://github.com// -GitHub username: -GitHub private access token: -Are these git repositories private? (yes|no): no -Do you need sample driver and emulator for trial?: (yes|no) yes - ---- -GitHub Config Repository: https://github.com// -GitHub Status Repository: https://github.com// -GitHub Username: -GitHub Access Token: *** -Use Private Repo: true - -Image Registry: ghcr.io/nttcom/kuesta -Version: latest -Deploy sample driver and emulator: true ---- - -Continue? (yes|no) yes +git submodule update --init --recursive ``` -KuestaはGitへのプッシュやプルリクエストの作成を行うため、GitHubの [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) (PAT) が必要です(classic推奨)。 -ここで入力されたPATは、ローカルのKubernetesクラスタ内のSecretリソースにのみ保存されます。ローカルのKubernetesクラスタを削除することで、どこにもデータを残さずに完全に削除できます。 +### envファイルの設定 +上でcloneしたK-SOTレポジトリに対して、以下envファイルを配置してください。 -インストールスクリプトの実行が完了したら、 `kubectl` コマンドを実行することで何がインストールされたかを確認できます。 - -1: Custom Resource Definitions(CRDs): +/.env ```bash -kubectl get customresourcedefinitions.apiextensions.k8s.io -```` - -```bash -NAME CREATED AT -buckets.source.toolkit.fluxcd.io 2023-01-10T06:31:20Z -certificaterequests.cert-manager.io 2023-01-10T06:31:19Z -certificates.cert-manager.io 2023-01-10T06:31:19Z -challenges.acme.cert-manager.io 2023-01-10T06:31:19Z -clusterissuers.cert-manager.io 2023-01-10T06:31:19Z -devicerollouts.kuesta.hrk091.dev 2023-01-10T06:43:30Z -gitrepositories.source.toolkit.fluxcd.io 2023-01-10T06:31:20Z -helmcharts.source.toolkit.fluxcd.io 2023-01-10T06:31:20Z -helmrepositories.source.toolkit.fluxcd.io 2023-01-10T06:31:20Z -issuers.cert-manager.io 2023-01-10T06:31:19Z -ocdemoes.kuesta.hrk091.dev 2023-01-10T06:43:36Z -ocirepositories.source.toolkit.fluxcd.io 2023-01-10T06:31:20Z -orders.acme.cert-manager.io 2023-01-10T06:31:19Z +KIND_NAME=ksot-started +GITHUB_REPO_URL=https://{Githubユーザー名}:{Githubユーザートークン}@github.com/{Githubユーザー名}/ksot-example +GITHUB_USER_NAME={Githubユーザー名} +GITHUB_USER_MAIL={Github登録メールアドレス} ``` -`kuesta.hrk091.dev`、`source.toolkit.fluxcd.io`、`cert-manager.io` に属するCRDが追加されていることが確認できます。 - - -2: Pods: +/github-server/config/overlays/test/.env ```bash -kubectl get pods -A | grep -v 'kube-system' +GITHUB_REPO_URL=https://{Githubユーザー名}:{Githubユーザートークン}@github.com/{Githubユーザー名}/ksot-example ``` -```bash -NAMESPACE NAME READY STATUS RESTARTS AGE -cert-manager cert-manager-7475574-t7qlm 1/1 Running 0 12m -cert-manager cert-manager-cainjector-d5dc6cd7f-wbh6r 1/1 Running 0 12m -cert-manager cert-manager-webhook-6868bd8b7-kc85s 1/1 Running 0 12m -device-operator-system device-operator-controller-manager-5d8648469b-57x4l 2/2 Running 0 11s -flux-system source-controller-7ff779586b-wsgf7 1/1 Running 0 12m -kuesta-getting-started gnmi-fake-oc01-79d4d679b4-tvm78 1/1 Running 0 10s -kuesta-getting-started gnmi-fake-oc02-69d9cc664d-56bsz 1/1 Running 0 10s -kuesta-getting-started subscriber-oc01 1/1 Running 0 9s -kuesta-getting-started subscriber-oc02 1/1 Running 0 9s -kuesta-system kuesta-aggregator-7586999c47-jj7m4 1/1 Running 0 27s -kuesta-system kuesta-server-85fc4f8646-kq72c 1/1 Running 0 27s -local-path-storage local-path-provisioner-9cd9bd544-lk9w9 1/1 Running 0 16m -provisioner-system provisioner-controller-manager-7675d487c8-w6f7x 1/2 Running 0 17s -``` - -全てのPodがRunningのステータスになっていたら、準備完了です。 - -以下の各namespaceに、Kuestaのコア機能として必要なサービスがデプロイされています。 - -- kuesta-system - - Kuestaのコア機能やAPIを提供するサーバ -- provisioner-system - - KuestaのKubernetesカスタムオペレータ。GitOpsやトランザクション管理に使用 -- flux-system - - FluxCDのカスタムコントローラ -- cert-manager - - プライベートCAの認証局、およびmTLS用の証明書発行 - -また、以下のnamespaceには、本チュートリアル用のリソースがデプロイされています。 - -- device-operator-system - - チュートリアルで使用する装置エミュレータに対し設定投入を行うためのドライバとして振る舞うKubernetesカスタムオペレータ -- kuesta-getting-started - - チュートリアルで使用する装置エミュレータやエミュレータに設定を行うためのKubernetesカスタムリソースなど - -以下の2つは、OpenConfig over gNMIで設定が可能な装置エミュレータです。本チュートリアルでは、 `oc01` と `oc02` の2つのエミュレータがデプロイされています。 - -```bash -kuesta-getting-started gnmi-fake-oc01-79d4d679b4-tvm78 1/1 Running 0 10s -kuesta-getting-started gnmi-fake-oc02-69d9cc664d-56bsz 1/1 Running 0 10s -``` - -ポートフォワーディングして `gnmic` からリクエストを行うことで設定されているコンフィグを確認できますので、必要に応じて実施してください。 -以下のコマンドで、装置エミュレータ内のコンフィグの確認ができます。 - -```bash -# oc01のコンフィグを取得 -kubectl -n kuesta-getting-started port-forward svc/gnmi-fake-oc01 9339:9339 -gnmic -a :9339 -u admin -p admin get --path "" --encoding JSON --skip-verify +### yangファイルの設定 +#### 装置向けyangの設定 +本記事で管理対象の装置とする[ODTN-emulator](https://github.com/opennetworkinglab/ODTN-emulator)の[YANGフォルダ]( https://github.com/opennetworkinglab/ODTN-emulator/tree/master/emulator-oc-cassini/yang/openconfig-odtn)内のyangを全て取得。```nb-server/pkg/tf/yang/devices```配下にフォルダ(名前: cassini)を作成して先ほど取得したyangファイルを配置してください。 +#### サービス向けyangの設定 +```nb-server/pkg/tf/yang/services```配下にフォルダ(名前: transceivers)を作成して以下内容のyangファイルをその中に配置します。 + +```yang +module transceivers { + namespace "tf-ksot/transceivers"; + prefix ts; + grouping transceivers-top { + list transceivers { + key "name"; + leaf name { + type string; + } + leaf-list up { + type string; + } + leaf-list down { + type string; + } + } + } + uses transceivers-top; +} ``` - -## Serviceコンフィグを作成し、GitOpsを走らせる - -**Service** は、ネットワークコンフィグを高レベルに抽象化したモデルです。Serviceを作成/変更することで、関連する複数のネットワーク装置にまとめて設定を投入することができます。 - -本チュートリアル用のサンプルレポジトリの中には、 `oc-circuit` という名のServiceが設定されていますので、これを用いて動作確認を行います。 -ServiceはCUEで記述されます。例として、 `oc-circuit` Serviceの定義を以下に示します。 - -```cue -package oc_circuit +### 装置設定導出パッケージの設定 +```nb-server/pkg/tf/transceivers.go```を以下内容で作成します。 +```go +package tf import ( - ocdemo "github.com/hrk091/kuesta-testdata/pkg/ocdemo" + "encoding/json" + "fmt" + + "github.com/nttcom-ic/ksot/nb-server/pkg/model/pathmap" ) -#Input: { - // kuesta:"key=1" - vlanID: uint32 - endpoints: [...{ - device: string - port: uint32 - }] +type Transceiver struct { + Name string `json:"name"` + Nos string `json:"nos"` + Up []string `json:"up"` + Down []string `json:"down"` } +type Transceivers map[string][]Transceiver -#Template: { - input: #Input - - output: devices: { - for _, ep in input.endpoints { - "\(ep.device)": config: { - ocdemo.#Device - - let _portName = "Ethernet\(ep.port)" - Interface: "\(_portName)": SubInterface: "\(input.vlanID)": { - Ifindex: ep.port - Index: input.vlanID - Name: "\(_portName).\(input.vlanID)" - AdminStatus: 1 - OperStatus: 1 +func TfTransceivers(ts interface{}) (map[string]pathmap.PathMapInterface, error) { + fmt.Println("hello") + mapByte, err := json.Marshal(ts) + if err != nil { + return nil, err + } + var transceivers Transceivers + if err := json.Unmarshal(mapByte, &transceivers); err != nil { + fmt.Println(err) + return nil, err + } + results := make(map[string]pathmap.PathMapInterface) + fmt.Println("tflogic: ", transceivers) + for _, devices := range transceivers { + for _, device := range devices { + result, err := pathmap.NewPathMap(map[string]interface{}{}) + if err != nil { + return nil, err + } + for _, v := range device.Up { + path := fmt.Sprintf("/openconfig-platform:components/component[name=%v]/openconfig-platform-transceiver:transceiver/config/enabled", v) + err = result.SetValue(path, true, map[string]string{}) + if err != nil { + return nil, err } - - Vlan: "\(input.vlanID)": { - VlanId: input.vlanID - Name: "VLAN\(input.vlanID)" - Status: ocdemo.#Vlan_Status_ACTIVE - Tpid: ocdemo.#OpenconfigVlanTypes_TPID_TYPES_UNSET + } + for _, v := range device.Down { + path := fmt.Sprintf("/openconfig-platform:components/component[name=%v]/openconfig-platform-transceiver:transceiver/config/enabled", v) + err = result.SetValue(path, false, map[string]string{}) + if err != nil { + return nil, err } } + results[device.Name] = result } } + fmt.Println("check: ", results) + return results, nil } ``` +```nb-server/pkg/tf/tf.go```を以下の内容に変更します。 +```go +package tf -`oc-circuit` Serviceは、`#Template` フィールドに定義された内容に従い、受け取った `#Template.input`（Serviceコンフィグ）を `#Template.output` （複数のネットワーク装置のコンフィグ）に変換します。 -`#Input` の定義されているServiceのインターフェーススキーマを見ると、`oc-circuit` Serviceを使用するためには、 VLAN ID と複数のネットワーク装置のポートが必要なことがわかります。 -これらを指定して `oc-circuit` Serviceを作成すると、 `#Template` のマッピング定義に従い、VLAN定義と指定したポートのVLANサブインターフェースが作成されます。 - -以下の手順にしたがって、`oc-circuit` Serviceを作成してください。 +import ( + "github.com/nttcom-ic/ksot/nb-server/pkg/model" +) -1: `oc-circuit` Serviceの作成をリクエストするために、以下のJSONファイルを `oc-circuit-vlan100.json` という名前で保存してください。 -このServiceでは、oc01とoc02の両エミュレータに対して、ポート番号1のインターフェイスにVLAN ID=100のVLANサブインターフェースを作成することをリクエストしています。 +var TfLogic = model.NewPathMapLogic() -```json -{ - "vlanID": 100, - "endpoints": [ - { - "device": "oc01", - "port": 1 - }, - { - "device": "oc02", - "port": 1 - } - ] +func init() { + // User needs to create a function to generate a pathmap and add it to the MAP. + // Example. + // TfLogic["serviceName"] = serviceName + TfLogic["transceivers"] = TfTransceivers } ``` -httpインターフェースを利用する場合、上に代わって以下JSONを作成してください。(pathにはServiceのパス、valueには投入するServiceの値を指定) - -```json -{ - "path": "/services/oc_circuit/100", - "value": { - "vlanID": 100, - "endpoints": [ - { - "device": "oc01", - "port": 1 - }, - { - "device": "oc02", - "port": 1 - } - ] - } -} -``` - -2: ローカルのKubernetesクラスタで動作しているKuestaサーバのPodに対してポートフォワーディングしてください。 - +## 4. 装置エミュレータを立ち上げる +事前にエミュレーターの接続情報を記載したenvファイルを追加 +/sb-server/config/overlays/test/.env ```bash -kubectl -n kuesta-system port-forward svc/kuesta-server 9339:9339 +cassini=root ``` -httpインターフェースを利用する場合は以下です。 - +以下コマンドで[OTDN-emulator](https://github.com/opennetworkinglab/ODTN-emulator)を立ち上げます。 ```bash -kubectl -n kuesta-system port-forward svc/kuesta-server 8080:8080 +docker pull onosproject/oc-cassini:0.21 +docker run -it -d --name odtn-emulator_openconfig_cassini_1 -p 11002:830 onosproject/oc-cassini:0.21 ``` -3: `gnmic`を用いて、Kuestaサーバに対してgNMI SetRequestを送ってください。 +以下のようにコンテナが立ち上がっているか確認してください。 ```bash -gnmic -a :9339 -u dummy -p dummy set --replace-path "/services/service[kind=oc_circuit][vlanID=100]" --encoding JSON --insecure --replace-file oc-circuit-vlan100.json +% docker ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +52da5c9f1c79 onosproject/oc-cassini:0.21 "sh /root/script/pus…" 4 hours ago Up 4 hours 22/tcp, 8080/tcp, 0.0.0.0:11002->830/tcp odtn-emulator_openconfig_cassini_1 ``` -httpインターフェースを利用する場合は、`curl`を用いてKuestaサーバに対して以下POST Requestを送ってください。 -```bash -curl -X POST -H "Content-Type: application/json" -d @oc-circuit-vlan100.json http://localhost:8080/set +コントローラーから[OTDN-emulator](https://github.com/opennetworkinglab/ODTN-emulator)への接続情報追加するため、K-SOTレポジトリに```sb-server/connect.json```を作成し以下の内容で保存します。 +```json +{ + "cassini": { + "ip": "host.docker.internal", + "port": 11002, + "username": "root", + "hostKeyVerify": false, + "if": "netconf" + } +} ``` -4: GitHubのWebコンソールを用いて、本チュートリアル向けに作成したコンフィグ用のGitHubレポジトリのプルリクエスト(PullRequest: PR)を確認してください。 -[PR一覧](https://github.com///pulls) にアクセスすると、 `[kuesta] Automated PR` というタイトルのPRが確認できます。 -PRのコメントを見ると、どのServiceとどのネットワーク装置が変更されたのかがわかりますし、 `Files changed` タブを確認すると詳細な変更点が確認できます。 - -5: PRブランチをマージする前に、ローカルのKubernetesクラスターで `DeviceRollout` リソースをモニターしてください。 `DeviceRollout` リソースは、Gitレポジトリからプルしたコンフィグを各ネットワーク装置に設定する際の状態管理を行っています。以下のコマンドを実行してください。 - +## 5. K-SOTのデプロイ +以下コマンドをK-SOTレポジトリのルートで実行してください。 ```bash -kubectl -n kuesta-getting-started get devicerollouts.kuesta.hrk091.dev -w +make getting-started ``` - -`DeviceRollout` リソースが一つ表示され、その `STATUS` が `Completed` になっていれば、GitOpsによるデリバリプロセスを流す準備は完了です。 +実行後```kubectl get pod```で起動しているpodを確認すると、以下3つのpodが作成されています。 ```bash -NAME PHASE STATUS -kuesta-testdata Healthy Completed +NAMESPACE NAME READY STATUS RESTARTS AGE +default ksot-github-deployment-766b6ff499-72zkr 1/1 Running 0 24s +default ksot-nb-deployment-967757888-dqzw7 1/1 Running 0 24s +default ksot-sb-deployment-6d89c6f85c-zksl5 1/1 Running 0 24s +... ``` - -6: GitHubのWebコンソール上で、PRをマージしてください。その後、 `DeviceRollout` をモニターしているターミナル画面に移動してください。 -1分以内に、 `DeviceRollout` の `STATUS` が `Running` に変わり、その後 `Completed` に変わることを確認してください。 +## 6. 動作確認 +### ポートフォワードの実施 +まずNorthboundとなるk8s serviceにport-forwardを実施しておきます。 ```bash -NAME PHASE STATUS -kuesta-testdata Healthy Completed -kuesta-testdata Healthy Completed -kuesta-testdata Healthy Running -kuesta-testdata Healthy Running -kuesta-testdata Healthy Running -kuesta-testdata Healthy Completed +kubectl port-forward svc/ksot-nb-service 8080:8080 ``` -7: 装置コンフィグが本当に更新されたのかを確認します。 `gnmic` を用いて、gNMI GetRequestをKuestaサーバに対して送り、装置コンフィグ全体を取得してください。 +### 装置情報の取得 +```PUT: http://localhost:8080/sync/devices```を実施し、Githubレポジトリに現在の装置設定を反映させます。 +検証用Githubレポジトリの```Devices/cassini```に以下のファイルが作成されていれば成功です。 +- actual.json: 実機から取得した設定 +- ref.json: 各サービスから設定されているパラメータ(初期値は空のJSON) +- set.json: コントローラーが投入した設定(初期値は実機から取得したものと同じ) -```bash -gnmic -a :9339 -u admin -p admin get --path "/devices/device[name=oc01]" --path "/devices/device[name=oc02]" --encoding JSON --insecure -``` -httpインターフェースを利用する場合は、`curl`を用いてKuestaサーバに対して以下POST Requestを送ってください。 -```bash -curl -X POST -H "Content-Type: application/json" -d '{"paths": ["/devices/oc01", "/devices/oc02"]}' http://localhost:8080/get +### サービスの作成 +以下JSONをbodyとして```POST: http://localhost:8080/services```を実施、bodyに指定されたサービスを作成し装置の設定を変更します。 +今回のサービスではtransceiversのud/downを実施するサービスを作成します。なお作成するサービスについては事前に装置設定導出パッケージを追加する必要があります(前の手順)。 +```JSON +{ + "transceivers": { + "transceivers:transceivers": [ + { + "name": "cassini", + "up": [], + "down": [ + "oe1", + "oe2", + ] + } + ] + } +} ``` - -以下のようなレスポンスが表示されます。 - -```json -[ - { - "source": ":9339", - "timestamp": 1673360105000000000, - "time": "2023-01-10T23:15:05+09:00", - "updates": [ - { - "Path": "devices/device[name=oc01]", - "values": { - "devices/device": { - "Interface": { - "Ethernet1": { - "AdminStatus": 1, - "Description": "awesome interface!!", - "Enabled": false, - "Mtu": 9000, - "Name": "Ethernet1", - "OperStatus": 1, - "Subinterface": { - "100": { - "AdminStatus": 1, - "Ifindex": 1, - "Index": 100, - "Name": "Ethernet1.100", - "OperStatus": 1 - }, - ... - }, - ... - }, - ... - }, - "Vlan": { - "100": { - "Member": [], - "Name": "VLAN100", - "Status": 1, - "Tpid": 0, - "VlanId": 100 - }, - ... +検証用Githubレポジトリの```Services/transceivers```に以下のファイルが作成されていることを確認してください。 +- input.json: 投入したサービスの値 +- output.json: 設定を変更した装置のxpathと対応する値 + +### 装置情報の取得(サービス作成後) +```PUT: http://localhost:8080/sync/devices```を実施し、Githubレポジトリに現在の装置設定を反映します。 +検証用Githubレポジトリの```Devices/cassini/actual.json```が以下のように更新され、[OTDN-emulator](https://github.com/opennetworkinglab/ODTN-emulator)の指定した箇所のtransceiversがdownしていることがわかります。 +```diff +{ +... + "name": "oe1", + "config": { + "name": "oe1" + }, + "state": { + "type": "openconfig-platform-types:TRANSCEIVER", + "empty": false + }, + "openconfig-platform-transceiver:transceiver": { + "config": { + - "enabled": true, + + "enabled": false, + "form-factor-preconf": "openconfig-transport-types:CFP2_ACO" + } + } +... + "name": "oe2", + "config": { + "name": "oe2" + }, + "state": { + "type": "openconfig-platform-types:TRANSCEIVER", + "empty": false + }, + "openconfig-platform-transceiver:transceiver": { + "config": { + - "enabled": true, + + "enabled": false + "form-factor-preconf": "openconfig-transport-types:CFP2_ACO" + } + } +... +} ``` -httpインターフェースを使用した場合のレスポンスは以下です。 -```json -[ - { - "Interface": { - "Ethernet1": { - "AdminStatus": 1, - "Description": "", - "Enabled": false, - "Mtu": 9000, - "Name": "Ethernet1", - "OperStatus": 1, - "SubInterface": { - "100": { - "AdminStatus": 1, - "Ifindex": 1, - "Index": 100, - "Name": "Ethernet1.100", - "OperStatus": 1 - } - }, - "Subinterface": {}, - "Type": 80 - }, - "Ethernet2": { - "AdminStatus": 1, - "Description": "", - "Enabled": false, - "Mtu": 9000, - "Name": "Ethernet2", - "OperStatus": 1, - "Subinterface": {}, - "Type": 80 - }, - "Ethernet3": { - "AdminStatus": 1, - "Description": "", - "Enabled": false, - "Mtu": 9000, - "Name": "Ethernet3", - "OperStatus": 1, - "Subinterface": {}, - "Type": 80 - } - }, - "Vlan": { - "100": { - "Member": [], - "Name": "VLAN100", - "Status": 1, - "Tpid": 0, - "VlanId": 100 - } - } - }, - { - "Interface": { - "Ethernet1": { - "AdminStatus": 1, - "Description": "", - "Enabled": false, - "Mtu": 9000, - "Name": "Ethernet1", - "OperStatus": 1, - "SubInterface": { - "100": { - "AdminStatus": 1, - "Ifindex": 1, - "Index": 100, - "Name": "Ethernet1.100", - "OperStatus": 1 - } - }, - "Subinterface": {}, - "Type": 80 - }, - "Ethernet2": { - "AdminStatus": 1, - "Description": "", - "Enabled": false, - "Mtu": 9000, - "Name": "Ethernet2", - "OperStatus": 1, - "Subinterface": {}, - "Type": 80 - }, - "Ethernet3": { - "AdminStatus": 1, - "Description": "", - "Enabled": false, - "Mtu": 9000, - "Name": "Ethernet3", - "OperStatus": 1, - "Subinterface": {}, - "Type": 80 - } - }, - "Vlan": { - "100": { - "Member": [], - "Name": "VLAN100", - "Status": 1, - "Tpid": 0, - "VlanId": 100 +### サービスの更新 +以下JSONをbodyとして```PUT: http://localhost:8080/services```を実施、bodyに指定されたサービスを更新し装置の設定を変更します。 +今回はoe1のtransceiverについてUPするよう更新します。 +```JSON +{ + "transceivers": { + "transceivers:transceivers": [ + { + "name": "cassini", + "up": [ + "oe1", + ], + "down": [ + "oe2", + ] } - } + ] } -] +} ``` -レスポンスを確認すると、oc01とoc02の両方の装置エミュレータに対して、VLAN ID=100のVLAN定義とVLANサブインターフェースが設定されていることが分かります。 -また、これらの装置コンフィグの変更内容はチュートリアル向けに作成したステータス用のGitレポジトリに対してコミット・プッシュされています。ステータス用のGitレポジトリのメインブランチのHEADを見ると、変更が保存されていることが確認できます。 - +### 装置情報の取得(サービス更新後) +```PUT: http://localhost:8080/sync/devices```を実施し、Githubレポジトリに現在の装置設定を反映します。 +検証用Githubレポジトリの```Devices/cassini/actual.json```が以下のように更新され、[OTDN-emulator](https://github.com/opennetworkinglab/ODTN-emulator)の指定した箇所のtransceiversがUPしていることがわかります。 +```diff +{ +... + "name": "oe1", + "config": { + "name": "oe1" + }, + "state": { + "type": "openconfig-platform-types:TRANSCEIVER", + "empty": false + }, + "openconfig-platform-transceiver:transceiver": { + "config": { + + "enabled": true, + - "enabled": false, + "form-factor-preconf": "openconfig-transport-types:CFP2_ACO" + } + } +... +} +``` -## ローカルKubernetesクラスタの削除 +### サービスの削除 +```DELETE: http://localhost:8080/services?name=transceivers```を実施。クエリパラメーターに指定した名前のサービスを削除し、装置の設定を変更します。 +検証用Githubレポジトリの```Services/transceivers```フォルダが消えるので確認してください。 -このチュートリアルで作成したローカルのKubernetesクラスタを削除するには、以下のコマンドを実行してください。 +### 装置情報の取得(サービス削除後) +```PUT: http://localhost:8080/sync/devices```を実施し、Githubレポジトリに現在の装置設定を反映します。 +検証用Githubレポジトリの```Devices/cassini/actual.json```が以下のように更新され、サービスから投入していたコンフィグ箇所が消えていることがわかります。 -```bash -kind delete cluster +```diff +{ +... + "name": "oe1", + "config": { + "name": "oe1" + }, + "state": { + "type": "openconfig-platform-types:TRANSCEIVER", + "empty": false + }, + "openconfig-platform-transceiver:transceiver": { + "config": { + - "enabled": true, + "form-factor-preconf": "openconfig-transport-types:CFP2_ACO" + } + } +... + "name": "oe2", + "config": { + "name": "oe2" + }, + "state": { + "type": "openconfig-platform-types:TRANSCEIVER", + "empty": false + }, + "openconfig-platform-transceiver:transceiver": { + "config": { + - "enabled": false + "form-factor-preconf": "openconfig-transport-types:CFP2_ACO" + } + } +... +} ``` -プライベートレポジトリのアクセス用に作成したPATは、不要であれば忘れずに削除しましょう。 +### 本項で使用している外部ツール +- [OTDN-emulator](https://github.com/opennetworkinglab/ODTN-emulator) \ No newline at end of file diff --git a/content/ja/docs/Guides/_index.md b/content/ja/docs/Guides/_index.md deleted file mode 100755 index 2e2ab7a..0000000 --- a/content/ja/docs/Guides/_index.md +++ /dev/null @@ -1,11 +0,0 @@ - ---- -title: "Guides" -linkTitle: "Guides" -weight: 4 -date: 2017-01-04 ---- - -{{% pageinfo %}} -作成中です。 -{{% /pageinfo %}} diff --git a/content/ja/docs/Installation/_index.md b/content/ja/docs/Installation/_index.md deleted file mode 100644 index 5b135c5..0000000 --- a/content/ja/docs/Installation/_index.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -title: "Installation" -linkTitle: "Installation" -weight: 2 -description: > - Kuestaのインストール手順 ---- - -Kuestaをインストールする手順を紹介します。 - -## はじめに - -バージョン1.24以上のKubernetesクラスターが必要です。 - -Kubernetesクラスターをお持ちでない場合は、kindを用いてローカルのKubernetesクラスターを作ることができます。 -[kindをインストール](https://kind.sigs.k8s.io/docs/user/quick-start/) し、`kind create cluster` を実行してクラスターを作成してください。 -これにより、ローカルで動作し `cluster-admin` 権限で操作出来るKubernetesクラスターが作成されます。 - - -## 事前準備 - -1. [kubectl](https://kubernetes.io/docs/tasks/tools/) をインストールしてください。Kubernetesクラスタに対してコマンドを実行する際に使用します。 -2[cue](https://cuelang.org/docs/install/) をインストールしてください。Kuestaのインストールスクリプトの実行に必要です。 - - -## Kuestaのインストール - - -Kuestaをインストールするには、以下のコマンドを実行してください。 - -```bash -git clone https://github.com/nttcom/kuesta.git -cd kuesta/tool/install -cue install -``` - -リリースバージョンを指定したい場合、もしくは別のコンテナレジストリを使用してインストールしたい場合は、 `version` もしくは `imageRegistry` タグを使用してください。 - -```bash -cue -t imageRegistry= -t version= install -``` - -プロンプトが表示されますので、指示に従ってパラメータを入力してください。 - -```bash -GitHub repository for config: https://github.com// -GitHub repository for status: https://github.com// -GitHub username: -GitHub private access token: -Are these git repositories private? (yes|no): no -Do you need sample driver and emulator for trial?: (yes|no) yes - ---- -GitHub Config Repository: https://github.com// -GitHub Status Repository: https://github.com// -GitHub Username: -GitHub Access Token: *** -Use Private Repo: true - -Image Registry: ghcr.io/nttcom/kuesta -Version: latest -Deploy sample driver and emulator: true ---- - -Continue? (yes|no) yes -``` - -KuestaはGitへのプッシュやプルリクエストの作成を行うため、GitHubの [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) (PAT) が必要です。 -上記で入力したPATは `kuesta-system/kuesta-secrets` という `Secret` リソースに保存され、kuestaサーバが git clone・pull・push・PullRequest作成を行うために使用されます。 - -また、非公開のGitレポジトリサーバに対してHTTPSで接続したい場合は、`GitRepository` を作成する際にこのPATを使うこともできます。Flux source-controllerにGitプライベートレポジトリへのアクセスを許可するために使用されます。 - - -## Flux source-controllerを用いてGitOpsを設定する - -Flux source-controllerを用いてGitOpsを行うには、IaCマニフェストを取得するソースを定義するために `GitRepository` リソースを作成する必要があります。 -以下は、[getting-started](/docs/getting-started) チュートリアルで作成された `GitRepository` のサンプルです。 - -```yaml -apiVersion: source.toolkit.fluxcd.io/v1beta2 -kind: GitRepository -metadata: - name: kuesta-testdata - namespace: kuesta-getting-started -spec: - interval: 1m0s - url: https://github.com/hrk091/kuesta-testdata - ref: - branch: main - secretRef: - name: kuesta-testdata-secret - timeout: 60s -``` - -`GitRepository`に関するより詳細な情報が知りたければ、[Fluxのドキュメント](https://fluxcd.io/flux/components/source/gitrepositories/)を参照してください。 - -Kuestaでは、`GitRepository`を作成するとKuestaのsource-watcherコントローラが検知して、対応する `DeviceRollout` を作成します。 -`DeviceRollout` は、マルチデバイスのトランザクション管理を責務とするカスタムリソースです。 -getting-started チュートリアルでは、以下の `DeviceRollout` が作成されます。 - -``` -apiVersion: kuesta.hrk091.dev/v1alpha1 -kind: DeviceRollout -metadata: - name: kuesta-testdata - namespace: kuesta-getting-started -spec: - deviceConfigMap: - oc01: - checksum: 1524caf17ec4c133f6f275326a6c9742a0155007f8eaa28ea601ce7ac39c0566 - gitRevision: main/30746f9beb48d237b6c0e0357708b3ed1f95cd1b - oc02: - checksum: 0b03381195ba613e0dd20e5d2683711e9d6082f0634bee7c54014de2eadf0fc9 - gitRevision: main/30746f9beb48d237b6c0e0357708b3ed1f95cd1b -status: - desiredDeviceConfigMap: - oc01: - checksum: 1524caf17ec4c133f6f275326a6c9742a0155007f8eaa28ea601ce7ac39c0566 - gitRevision: main/30746f9beb48d237b6c0e0357708b3ed1f95cd1b - oc02: - checksum: 0b03381195ba613e0dd20e5d2683711e9d6082f0634bee7c54014de2eadf0fc9 - gitRevision: main/30746f9beb48d237b6c0e0357708b3ed1f95cd1b - deviceStatusMap: - oc01: Completed - oc02: Completed - phase: Healthy - status: Completed -``` - -`DeviceRollout` の管理はライフサイクル全体を通じて自動化されていますので、作成や変更を行う必要はありません。 - - -## Installing Device Driver and configuring Device Custom Resource - -{{% pageinfo %}} - -以降の記述は、getting-started チュートリアルで使用されているサンプルのKubernetesカスタムオペレータを使用した場合に限定した内容になります。 -Kuestaを用いて制御したいターゲットデバイスと、その制御のために実装したKubernetesカスタムオペレータによって、詳細な手順は異なります。 - -{{% /pageinfo %}} - -OpenConfig over gNMIをサポートしているデバイスに設定を投入したい場合は、[kuesta/device-operator](https://github.com/nttcom/kuesta/tree/main/device-operator) で開発されているサンプルのKubernetesカスタムオペレータを利用できます。 -このサンプルのKubernetesカスタムオペレータは[基本的なOpenConfig YANGセット](https://github.com/nttcom/kuesta/tree/main/device-operator/pkg/model/yang)をサポートしているデバイスに特化していますが、[OpenConfigスタイル](https://github.com/openconfig/public/blob/master/doc/openconfig_style_guide.md)に準拠しているYANGであれば任意に追加して拡張することが可能です。 - -このKubernetesカスタムオペレータは `make` コマンドもしくは `kubectl/kustomize` を直接実行することでインストールできますが、 -Kuestaのインストールスクリプトを使用するのが一番簡単です。Kuestaのインストールスクリプトを実行すると `getting-started` という名前でkustomizeのオーバレイディレクトリが作成されますので、これをテンプレートとして自由にカスタムできます。 - -`getting-started` オーバレイディレクトリを用いてKubernetesカスタムオペレータをインストールするには、以下のコマンドを実行します: - -```bash -export IMG=ghcr.io/nttcom/kuesta/device-operator:latest -export KUSTOMIZE_ROOT=overlays/getting-started -make deploy -``` - -Kuestaからデバイスに対して設定投入するためには、Kubernetesカスタムオペレータに加えて、各デバイスごとにカスタムリソースを作成する必要があります。 -getting-startedチュートリアルでは、gNMIエミュレータ `oc01` に対して以下のような `OcDemo` カスタムリソースを作成します。 - -```yaml -apiVersion: kuesta.hrk091.dev/v1alpha1 -kind: OcDemo -metadata: - name: oc01 - namespace: kuesta-getting-started -spec: - address: gnmi-fake-oc01.kuesta-getting-started - port: 9339 - rolloutRef: kuesta-testdata - tls: - secretName: oc01-cert - skipVerify: true -``` - -`OcDemo` リソースでは、設定投入を行うターゲットデバイスの接続情報、アドレス、ポート、ユーザ名とパスワード、TLS関連設定、などを定義します。 -`.spec.rolloutRef` フィールドは、Flux source-controllerのGitOpsによって提供されるコンフィグの更新通知を、どの `DeviceRollout` から取得するかを指定するフィールドであり、必須項目です。 -`OcDemo` リソースの `.spec` についてより詳細な情報が知りたければ、 `kubectl explain ocdemo.spec` を実行して確認してください。 diff --git a/content/ja/docs/Reference/_index.md b/content/ja/docs/Reference/_index.md index c70670a..2077f2f 100644 --- a/content/ja/docs/Reference/_index.md +++ b/content/ja/docs/Reference/_index.md @@ -3,22 +3,14 @@ title: "Reference" linkTitle: "Reference" weight: 6 description: > - Kuestaの参考情報 + K-SOTの参考情報 --- -- CUE - - [cuelang.org](https://cuelang.org/docs/) - - [Cuetorial](https://cuetorials.com/) -- FluxCD - - [gitops-toolkit](https://fluxcd.io/flux/gitops-toolkit/) - - [source-controller](https://fluxcd.io/flux/components/source/) - - [source-watcher](https://fluxcd.io/flux/gitops-toolkit/source-watcher/) -- Kubernetes Custom Operator - - [kubebuilder](https://book.kubebuilder.io/) -- OpenConfig - - [YANG models](https://github.com/openconfig/public/tree/master/release/models) - - [OpenConfig Style](https://github.com/openconfig/public/blob/master/doc/openconfig_style_guide.md) -- ygot (YANG Go Tools) - - [Example of go struct generation](https://github.com/openconfig/ygot/tree/master/demo/getting_started) -- gNMI - - [Specification](https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-specification.md) +- Kubernetes + - [document](https://kubernetes.io/ja/) +- Go + - [document](https://go.dev/) +- YANG + - [RFC6020](https://datatracker.ietf.org/doc/html/rfc6020) +- NETCONF + - [RFC4741](https://datatracker.ietf.org/doc/html/rfc4741) diff --git a/content/ja/docs/_index.md b/content/ja/docs/_index.md index 7fe830b..f9bff6e 100755 --- a/content/ja/docs/_index.md +++ b/content/ja/docs/_index.md @@ -8,6 +8,6 @@ menu: weight: 10 --- -Kuestaは、クラウドネイティブなアプローチでネットワークのInfrastructure as Codeを可能にするオープンソースのフレームワークです。 +K-SOTは、クラウドネイティブなアプローチでネットワークのInfrastructure as Codeを可能にするオープンソースのフレームワークです。 ネットワークの高レベルなモデルへの抽象化とCUE言語を用いたデータマッピング、Kubernetesカスタムオペレータを用いたGitOpsなどで構成され、 ソフトウェア開発のIaCやGitOpsで培われたプラクティスをネットワークに適用し、高度なネットワーク設定の自動化を実現します。