diff --git a/docs/user-guide/configuration/schemas.md b/docs/user-guide/configuration/schemas.md index 254aa00..f3359ff 100644 --- a/docs/user-guide/configuration/schemas.md +++ b/docs/user-guide/configuration/schemas.md @@ -6,14 +6,13 @@ This process is facilitated through the Schema CustomResource, detailed [here](l The Schema CustomResource is configured using three main parameter groups: -1. __Source of Schema__: Determined by `repoURL`, `kind`, and `ref` parameters. +1. __Source of Schema__: Determined by `repoURL`, `kind`, `ref`, `dirs`, `credentials`, and `proxy` parameters. 2. __Schema Identification__: Specified using `provider` and `version` parameters. 3. __Schema Parsing Method__: Configured through `models`, `includes`, and `excludes` parameters. ## Source of Schema: Repository Configuration -To successfully retrieve the schema, it is essential for users to provide four key parameters: `repoURL`, `kind`, `ref` and `credentials`. -These parameters jointly establish the methodology for schema acquisition: +To successfully retrieve the schema, three parameters are always required: `repoURL`, `kind`, and `ref`. The `credentials` parameter is required only when the repository is private. Together these parameters establish the methodology for schema acquisition: * `repoURL`: This parameter is pivotal as it specifies the repository's URL where the schema is located. * `kind`: It determines the nature of the reference point within the repository, offering options between a "tag" or a "branch". @@ -101,6 +100,10 @@ The schema is uniquely identified through `provider` and `version`. * `provider`: Contains details about the schema issuer, typically including vendor and chassis type. * `version`: Represents the specific version of the schema. +!!!note "One Schema CR per vendor release and platform type" + + SDC uses a separate Schema CR for each combination of vendor, platform type, and release. If a vendor supports multiple platform types with different feature sets, define a separate Schema CR for each — using a distinct `provider` value (for example `ocnos-otherplatform.ipinfusion.sdcio.dev`) and adjusting `models` or `excludes` to match that platform's supported feature set. + ## Schema Parsing Method: Handling YANG Models YANG schemas are comprised of several implemented models, some of which may have dependencies on other models. @@ -120,8 +123,8 @@ If your vendor/model is not yet documented, use the workflow below. Choose a repository and pin a specific `tag` or `branch`. -* Use `kind: tag` whenever possible for reproducibility. -* Use `ref` to pin the exact release (for example: `OcNOS-SP-7.0.0`). +* Use `kind: tag` whenever possible for reproducibility. Set `ref` to the exact release tag (for example: `OcNOS-SP-7.0.0`). +* Use `kind: branch` only when you need to track a mutable branch — for example, during active development or when a vendor does not publish tags. Set `ref` to the branch name (for example: `main`). Be aware that branch references are not pinned: the schema will re-clone on the next reconciliation, which can introduce unexpected changes. ### 2. Locate model roots and dependencies @@ -141,7 +144,7 @@ Start with a narrow scope, then expand: * Add `includes` for dependency folders/files. * Use `excludes` to skip known unwanted trees. -### 4. Validate locally with `sdc-lite` (primary) +### 4. Validate locally with `sdc-lite` Use `sdc-lite` to validate that your Schema CR definition is functional before cluster apply. @@ -204,68 +207,6 @@ Typical fixes: * Add directories/files to `includes`. * Reduce `models` scope and onboard incrementally. -## OcNOS SP-7.0.0 (IP Infusion) - -This example onboards the native `ipi-*` YANG models for OcNOS SP-7.0.0. - -Source repository details: - -* Repository: `https://github.com/IPInfusion/OcNOS` -* Release tag: `OcNOS-SP-7.0.0` -* Native model path: `yang-files/ipi` - -The OcNOS repository does not ship the IETF base types (`ietf-inet-types`, `ietf-yang-types`) that many `ipi-*` modules import. -A second `repositories` entry pulls those from [YangModels/yang](https://github.com/YangModels/yang), following the same pattern used for Arista. - -```yaml -apiVersion: inv.sdcio.dev/v1alpha1 -kind: Schema -metadata: - name: ocnos-sp.ipinfusion.sdcio.dev-7.0.0 - namespace: default -spec: - provider: ocnos-sp.ipinfusion.sdcio.dev - version: 7.0.0 - repositories: - - repoURL: https://github.com/IPInfusion/OcNOS - kind: branch - ref: OcNOS-SP-7.0.0 - dirs: - - src: yang-files/ipi - dst: ipi - schema: - models: - - ipi - - repoURL: https://github.com/YangModels/yang - kind: branch - ref: main - dirs: - - src: standard/ietf/RFC - dst: ietf - schema: - includes: - - ietf/ietf-inet-types.yang - - ietf/ietf-yang-types.yang -``` - -To apply: - -```shell -sdc-lite schema load -t ocnos-sp-7-0-0 -f config-server-repo/example/schemas/schema-ipinfusion-ocnos-sp-7.0.0.yaml -sdc-lite target show -t ocnos-sp-7-0-0 -``` - -Cluster apply (optional after local validation): - -```shell -kubectl apply -f schema-ipinfusion-ocnos-sp-7.0.0.yaml -kubectl get schema ocnos-sp.ipinfusion.sdcio.dev-7.0.0 -o yaml -``` - -!!!note "Platform-specific schemas" - - SDC uses a separate Schema CR per vendor release and platform type. For a different OcNOS platform, define a new Schema with a different `provider` value (for example `ocnos-otherplatform.ipinfusion.sdcio.dev`) and adjust `models` or `excludes` to match that platform's supported feature set. - ## Examples ### SR Linux v24.10.1 @@ -412,4 +353,38 @@ config-server-repo/example/schemas/schema-arista-4.31.1f.yaml --8<-- config-server-repo/example/schemas/schema-arista-4.33.0f.yaml --8<-- -``` \ No newline at end of file +``` + +### OcNOS SP-7.0.0 (IP Infusion) + +This example onboards the native `ipi-*` YANG models for OcNOS SP-7.0.0. + +Source repository details: + +* Repository: `https://github.com/IPInfusion/OcNOS` +* Release tag: `OcNOS-SP-7.0.0` +* Native model path: `yang-files/ipi` + +The OcNOS repository does not ship the IETF base types (`ietf-inet-types`, `ietf-yang-types`) that many `ipi-*` modules import. +A second `repositories` entry pulls those from [YangModels/yang](https://github.com/YangModels/yang), following the same pattern used for Arista. + +```yaml +--8<-- +config-server-repo/example/schemas/schema-ipinfusion-ocnos-sp-7.0.0.yaml +--8<-- +``` + +To apply: + +```shell +sdc-lite schema load -t ocnos-sp-7-0-0 -f config-server-repo/example/schemas/schema-ipinfusion-ocnos-sp-7.0.0.yaml +sdc-lite target show -t ocnos-sp-7-0-0 +``` + +Cluster apply (optional after local validation): + +```shell +kubectl apply -f schema-ipinfusion-ocnos-sp-7.0.0.yaml +kubectl get schema ocnos-sp.ipinfusion.sdcio.dev-7.0.0 -o yaml +``` +