From a46043a9cc7420823f3687257e13af706fcf32ad Mon Sep 17 00:00:00 2001 From: Roman Dodin Date: Sun, 6 Oct 2024 18:04:10 +0300 Subject: [PATCH 1/4] 0.3.0 release notes --- docs/ndk/releases/0.3.md | 18 ++++++++++++++++++ docs/ndk/releases/index.md | 10 ++++++---- mkdocs.yml | 1 + 3 files changed, 25 insertions(+), 4 deletions(-) create mode 100644 docs/ndk/releases/0.3.md diff --git a/docs/ndk/releases/0.3.md b/docs/ndk/releases/0.3.md new file mode 100644 index 00000000..127bb038 --- /dev/null +++ b/docs/ndk/releases/0.3.md @@ -0,0 +1,18 @@ +--- +version: v0.3.0 +prev_version: v0.2.0 +--- +# NDK -{{version}}- Release Notes + +* Documentation - [ndk.srlinux.dev](https://ndk.srlinux.dev/doc/sdk?version=-{{version}}-) +* Introduced with SR Linux `v24.3.1`. +* Diff with the previous release: [`-{{prev_version}}-...-{{version}}-`](https://github.com/nokia/srlinux-ndk-protobufs/compare/-{{prev_version}}-...-{{version}}-) + +## Configuration Acknowledgements + +To allow NDK agents to explicitly acknowledge the received configuration a new agent registration option - `wait_config_ack` - has been added to the [`AgentRegistrationRequest`][agent-reg-req-doc]. + +To facilitate acknowledgment exchange, a new gRPC service - [`SdkMgrConfigService`][sdk-mgr-config-svc-doc] - has been introduced in this release. Clients (NDK agents) send `AcknowledgeConfigRequest` to the NDK server to explicitly acknowledge each configuration update they received. + +[agent-reg-req-doc]: https://ndk.srlinux.dev/doc/sdk?version=-{{version}}-#AgentRegistrationRequest +[sdk-mgr-config-svc-doc]: https://ndk.srlinux.dev/doc/config?version=-{{version}}-#SdkMgrConfigService diff --git a/docs/ndk/releases/index.md b/docs/ndk/releases/index.md index 9f12cb6e..43741394 100644 --- a/docs/ndk/releases/index.md +++ b/docs/ndk/releases/index.md @@ -5,16 +5,18 @@ For the same reason the NDK versioning scheme is different from the SR Linux's o At the same time, new NDK release appear together with a certain SR Linux release where NDK updates were made. -/// note | Semantic Versioning and Non Backwards Compatible Changes +/// admonition | Semantic Versioning and Non Backwards Compatible Changes + type: subtle-note Semantic Versioning imposes certain rules on how to version software releases. The most important one is that a new major version release (e.g. 2.0.0) may contain non backwards compatible changes. -Since NDK is versioned with `v0` at the moment of this writing, we are not bound by this rule and may introduce non backwards compatible changes in any release. The NBC changes would be mentioned in the release notes. +Since NDK is versioned with `v0`, we may introduce non backwards compatible changes in the forthcoming releases until we reach `v1`. The non-backwards compatible (NBC) changes will be mentioned in the release notes. /// The following table shows the mapping between SR Linux and NDK releases: | NDK Release | SR Linux Release[^10] | Comments | -| ---------------- | ---------------- | -------- | -| [v0.2.0](0.2.md) | 23.10.1 | | +| ---------------- | --------------------- | -------- | +| [v0.2.0](0.2.md) | 23.10.1 | | +| [v0.3.0](0.3.md) | 24.3.1 | | [^10]: SR Linux release where NDK changes were introduced. diff --git a/mkdocs.yml b/mkdocs.yml index 68998187..ba3e6088 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -80,6 +80,7 @@ nav: - Releases: - ndk/releases/index.md - 0.2: ndk/releases/0.2.md + - 0.3: ndk/releases/0.3.md - Ansible: - ansible/index.md - nokia.srlinux collection: From 8e9c0b63b299531cafeb5499c1ae38f314d29daa Mon Sep 17 00:00:00 2001 From: Roman Dodin Date: Sat, 26 Oct 2024 07:26:10 +0200 Subject: [PATCH 2/4] added ndk 0.3.0 changelog --- docs/ndk/releases/0.3.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/ndk/releases/0.3.md b/docs/ndk/releases/0.3.md index 127bb038..cbd8d4d2 100644 --- a/docs/ndk/releases/0.3.md +++ b/docs/ndk/releases/0.3.md @@ -5,6 +5,8 @@ prev_version: v0.2.0 # NDK -{{version}}- Release Notes * Documentation - [ndk.srlinux.dev](https://ndk.srlinux.dev/doc/sdk?version=-{{version}}-) +* Protobuf definitions - [github.com/nokia/srlinux-ndk-protobufs](https://github.com/nokia/srlinux-ndk-protobufs/tree/-{{version}}-) +* Language bindings - [Go](https://github.com/nokia/srlinux-ndk-go/tree/-{{version}}-), [Python](https://github.com/nokia/srlinux-ndk-py/tree/-{{version}}-). * Introduced with SR Linux `v24.3.1`. * Diff with the previous release: [`-{{prev_version}}-...-{{version}}-`](https://github.com/nokia/srlinux-ndk-protobufs/compare/-{{prev_version}}-...-{{version}}-) From ac3f73007ec6eaac68e838c95306c58a27cff386 Mon Sep 17 00:00:00 2001 From: Roman Dodin Date: Sat, 26 Oct 2024 09:10:19 +0200 Subject: [PATCH 3/4] added 0.4.0 ndk release notes --- docs/ndk/guide/dev/go/index.md | 13 ++++++++++++- docs/ndk/releases/0.4.md | 35 ++++++++++++++++++++++++++++++++++ docs/ndk/releases/index.md | 11 ++++++----- mkdocs.yml | 1 + 4 files changed, 54 insertions(+), 6 deletions(-) create mode 100644 docs/ndk/releases/0.4.md diff --git a/docs/ndk/guide/dev/go/index.md b/docs/ndk/guide/dev/go/index.md index 8815b5e3..4d3f7305 100644 --- a/docs/ndk/guide/dev/go/index.md +++ b/docs/ndk/guide/dev/go/index.md @@ -32,9 +32,19 @@ The toolchain that can be used to develop and build Go-based NDK apps consists o Goreleaser is optional, but it is a nice tool to build and release Go-based NDK applications in an automated fashion. ## Bond or no Bond? + +The [**`srl-labs/bond`**][bond-repo] package is a helper Go [package][bond-pkg] that abstracts the low-level NDK API and assists in the development of the NDK applications. It is a wrapper around the NDK gRPC services with utility functions that were designed to provide a more pleasant development experience. -The [**`srl-labs/bond`**][bond-repo] package is a helper Go package that abstracts the low-level NDK API and assists in the development of the NDK applications. It is a wrapper around the NDK gRPC services with utility functions that were designed to provide a more pleasant development experience. +Bond takes care of the following tasks: +* registering the NDK agent with the NDK server +* creation of NDK gRPC clients for the NDK services +* creation of gNMI client to interact with SR Linux gNMI server and providing the GetWithGNMI method to +* receiving the notifications from the NDK services +* aggregating configuration notifications and forwarding the aggregated config to the NDK application +* handling of the NDK application graceful shutdown + + Since using `bond` is optional, we provide two documentation sets for a basic NDK app development: 1. With Bond - a development workflow that leverages [bond][bond-repo] package. @@ -73,3 +83,4 @@ Let's see how we can develop this app using the `bond` package. [greeter-go-repo]: https://github.com/srl-labs/ndk-greeter-go [bond-repo]: https://github.com/srl-labs/bond +[bond-pkg]: https://pkg.go.dev/github.com/srl-labs/bond diff --git a/docs/ndk/releases/0.4.md b/docs/ndk/releases/0.4.md new file mode 100644 index 00000000..81c9d50f --- /dev/null +++ b/docs/ndk/releases/0.4.md @@ -0,0 +1,35 @@ +--- +version: v0.4.0 +prev_version: v0.3.0 +--- +# NDK -{{version}}- Release Notes + +* Documentation - [ndk.srlinux.dev](https://ndk.srlinux.dev/doc/sdk?version=-{{version}}-) +* Protobuf definitions - [github.com/nokia/srlinux-ndk-protobufs](https://github.com/nokia/srlinux-ndk-protobufs/tree/-{{version}}-) +* Language bindings - [Go](https://github.com/nokia/srlinux-ndk-go/tree/-{{version}}-), [Python](https://github.com/nokia/srlinux-ndk-py/tree/-{{version}}-). +* Introduced with SR Linux `v24.10.1`. +* Diff with the previous release: [`-{{prev_version}}-...-{{version}}-`](https://github.com/nokia/srlinux-ndk-protobufs/compare/-{{prev_version}}-...-{{version}}-) + +## Project Bond + +--8<-- "docs/ndk/guide/dev/go/index.md:bond-intro" + +We have created a tutorial demonstrating how to use Bond to develop a simple [NDK Greeter](../guide/dev/go/with-bond/index.md) application in Go. +Developing NDK agents is much simpler with the help of the [Bond][bond-repo] package and we recommend new users to start with it. + +## Disabled NDK caching + +Starting with SR Linux 24.10.1 caching will be disabled by default for all NDK services except Network instance, Appid, and Config. This is done to ensure high performance of the NDK server while keeping the memory consumption low. + +A user can enable caching by registering the agent with the `enable_cache` registration option against the NDK manager server. With disabled caching, the services will have to use `CreateOrUpdate` SDK Manager Operation, instead of a separate `Create` and `Update` operations. + +## Auto Telemetry State + +The [`auto_telemetry_state`][ats-proto] field has been added to the `AgentRegistrationRequest` message to instruct the NDK server to automatically mirror the NDK app's configuration to the state database. + +When this field is set to `true`, the application will no longer need to set the its configuration to state manually via Telemetry service. This can be useful for applications that do not manage their own state and only need to have configuration values. For such apps, it is no longer needed to update the state manually as it will be done automatically by the NDK server. + +[bond-repo]: https://github.com/srl-labs/bond + +[bond-pkg]: https://pkg.go.dev/github.com/srl-labs/bond +[ats-proto]: https://github.com/nokia/srlinux-ndk-protobufs/blob/v0.4.0/ndk/sdk_service.proto#L69 diff --git a/docs/ndk/releases/index.md b/docs/ndk/releases/index.md index 43741394..9bd4766d 100644 --- a/docs/ndk/releases/index.md +++ b/docs/ndk/releases/index.md @@ -14,9 +14,10 @@ Since NDK is versioned with `v0`, we may introduce non backwards compatible chan The following table shows the mapping between SR Linux and NDK releases: -| NDK Release | SR Linux Release[^10] | Comments | -| ---------------- | --------------------- | -------- | -| [v0.2.0](0.2.md) | 23.10.1 | | -| [v0.3.0](0.3.md) | 24.3.1 | | +| NDK Release | SR Linux Release[^1] | Comments | +| ---------------- | -------------------- | -------- | +| [v0.2.0](0.2.md) | 23.10.1 | | +| [v0.3.0](0.3.md) | 24.3.1 | | +| [v0.4.0](0.4.md) | 24.10.1 | | -[^10]: SR Linux release where NDK changes were introduced. +[^1]: SR Linux release where NDK changes were introduced. diff --git a/mkdocs.yml b/mkdocs.yml index ba3e6088..92197675 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -81,6 +81,7 @@ nav: - ndk/releases/index.md - 0.2: ndk/releases/0.2.md - 0.3: ndk/releases/0.3.md + - 0.4: ndk/releases/0.4.md - Ansible: - ansible/index.md - nokia.srlinux collection: From 7c05c6794670153f96a9e735a0183bd00d924253 Mon Sep 17 00:00:00 2001 From: Roman Dodin Date: Sat, 26 Oct 2024 10:08:59 +0200 Subject: [PATCH 4/4] fix admonition --- docs/ndk/guide/dev/py/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/ndk/guide/dev/py/index.md b/docs/ndk/guide/dev/py/index.md index c03e02c6..81f402ff 100644 --- a/docs/ndk/guide/dev/py/index.md +++ b/docs/ndk/guide/dev/py/index.md @@ -1,6 +1,7 @@ # Python Development Environment -/// warning "Work in progress" +/// admonition | Work in progress + type: warning This tutorial might be outdated. Please check Go tutorial for the latest updates until this version is updated. ///