From 5a9d667927f2fd6967658b2bc3400a84b8b2b7fd Mon Sep 17 00:00:00 2001 From: Tareque Hossain Date: Tue, 26 May 2026 18:44:26 -0700 Subject: [PATCH 1/2] docs: Add Getting Started section for REST API in Fern Signed-off-by: Tareque Hossain --- docs/index.yml | 5 +++ docs/openapi/getting_started.md | 74 +++++++++++++++++++++++++++++++++ fern/.gitignore | 2 + fern/README.md | 27 ++++++++++++ fern/docs.yml | 3 +- fern/generators.yml | 1 - 6 files changed, 110 insertions(+), 2 deletions(-) create mode 100644 docs/openapi/getting_started.md create mode 100644 fern/README.md diff --git a/docs/index.yml b/docs/index.yml index e490df1003..c9436e9721 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -14,6 +14,7 @@ navigation: - page: Home path: index.md + icon: home - section: Overview contents: @@ -212,4 +213,8 @@ navigation: - tab: api layout: + - page: Getting Started + path: openapi/getting_started.md + icon: flower - api: API Reference + tag-description-pages: true diff --git a/docs/openapi/getting_started.md b/docs/openapi/getting_started.md new file mode 100644 index 0000000000..6c7d0031d3 --- /dev/null +++ b/docs/openapi/getting_started.md @@ -0,0 +1,74 @@ +This section provides a quick overview of the API and how to get started. + +### Authentication +The first step is to authenticate using a JWT bearer token. Organization structures and roles depend on the authentication configuration used. For details on authentication, please consult the +NICo REST `auth` module [README](https://github.com/NVIDIA/infra-controller-rest/tree/main/auth). + +### API Version +The next step is to be aware of the API version being used. The API version can be retrieved by calling the [Retrieve Metadata endpoint](/infra-controller/rest-api-reference/api-reference/metadata/get-metadata). In general, the API maintains backward +compatibility with the previous versions. Any breaking changes are announced using a deprecation notice. Current and past deprecations are listed in the [Deprecations](/infra-controller/rest-api-reference/deprecations) section. + +### Service Account Mode +Depending on the auth configuration used, the NICo REST API may be configured in Service Account mode. In this mode, API users can act as both Provider and Tenant as part of the same organization. +If this is the case, the user must first retrieve the Service Account by making a call to the [Retrieve Service Account endpoint](/infra-controller/rest-api-reference/api-reference/service-account/get-current-service-account). +For service accounts, the Tenant entity is initialized as a privileged Tenant with `targetedInstanceCreation` capability enabled. + +### Provider or Tenant Mode +If NICo REST API is not configured in Service Account mode, the user should retrieve the Infrastructure Provider by making a call to the [Retrieve Infrastructure Provider endpoint](/infra-controller/rest-api-reference/api-reference/infrastructure-provider/get-current-infrastructure-provider) +or the Tenant by making a call to the [Retrieve Tenant endpoint](/infra-controller/rest-api-reference/api-reference/tenant/get-current-tenant). + +In both cases, these calls initialize Provider and Tenant entities for the organization. All resources created are anchored to either the Provider or Tenant entity. + +Once the Provider and the Tenant are initialized, the user can create resources by making calls to the appropriate endpoints. + +### Creating Site Level IP Blocks +To utilize a NICo Site, the Provider or Service Account holder must create IP Blocks for each network overlay defined in NICo Site configuration toml file. + +To create an IP Block, the user must make a call to the [Create IP Block endpoint](/infra-controller/rest-api-reference/api-reference/ip-block/create-ipblock). + +> **Note:** From this point onwards, a brief outline is provided for the typical API call flows for various use cases. + +### Typical API Call Flow for Service Account + +- Retrieve available Sites using the [Retrieve All Sites endpoint](/infra-controller/rest-api-reference/api-reference/site/get-all-site) and choose a Site to create resources in. For _Disconnected_ NICo installations where NICo +REST is deployed alongside NICo Core, typically there will be a single Site available. +- For each Site IP Block, create a Network Allocation for the Tenant entity using the [Create Allocation endpoint](/infra-controller/rest-api-reference/api-reference/allocation/create-allocation) using the full prefix length. +This will create a Tenant IP Block for each Site IP Block. +- Creating an Allocation will create the Tenant in NICo Core. +- Create a VPC using the [Create VPC endpoint](/infra-controller/rest-api-reference/api-reference/vpc/create-vpc). +- Create a VPC Prefix or Subnet referencing the VPC and a Tenant IP Block +- If the Site supports Native Networking (FNN), create a VPC Prefix using the [Create VPC Prefix endpoint](/infra-controller/rest-api-reference/api-reference/vpc-prefix/create-vpc-prefix). Otherwise the user should create a Subnet +using the [Create Subnet endpoint](/infra-controller/rest-api-reference/api-reference/subnet/create-subnet). +- Create an Operating System using the [Create Operating System endpoint](/infra-controller/rest-api-reference/api-reference/operating-system/create-operating-system) specifying iPXE script and user data. +- Retrieve available Machines on Site using the [Retrieve All Machines endpoint](/infra-controller/rest-api-reference/api-reference/machine/get-all-machine) +- Create an Instance specifying the VPC, VPC Prefix or Subnet, Operating System, and Machine + +### Typical API Call Flow for Provider + +- Create a Tenant Account using the [Create Tenant Account endpoint](/infra-controller/rest-api-reference/api-reference/tenant-account/create-tenant-account). Provider must know the Tenant org name. +- Once the Tenant has accepted the Tenant Account, the Provider can allocate resources to the Tenant. +- Retrieve available Sites using the [Retrieve All Sites endpoint](/infra-controller/rest-api-reference/api-reference/site/get-all-site) and choose a Site to create resources in. +- Create an Instance Type using the [Create Instance Type endpoint](/infra-controller/rest-api-reference/api-reference/instance-type/create-instance-type) +- Retrieve available Machines on Site using the [Retrieve All Machines endpoint](/infra-controller/rest-api-reference/api-reference/machine/get-all-machine) +- Update a Machine's Instance Type using the [Update Machine endpoint](/infra-controller/rest-api-reference/api-reference/machine/update-machine) or assign multiple Machines to an Instance Type using the +[Create Instance Type/Machine Association endpoint](/infra-controller/rest-api-reference/api-reference/instance-type/create-instance-type-machine-association) +- Create a Compute Allocation for Tenant using the [Create Compute Allocation endpoint](/infra-controller/rest-api-reference/api-reference/allocation/create-allocation) referencing the Instance Type +- Creating any type of Allocation for a Tenant will create the Tenant in NICo Core. +- Create a Network Allocation for Tenant using the [Create Allocation endpoint](/infra-controller/rest-api-reference/api-reference/allocation/create-allocation) referencing a Site IP Block +- Creating a Network Allocation will create a Tenant IP Block + +### Typical API Call Flow for Tenant + +- Accept the Tenant Account using the [Update Tenant Account endpoint](/infra-controller/rest-api-reference/api-reference/tenant-account/update-tenant-account). +- Retrieve available Sites using the [Retrieve All Sites endpoint](/infra-controller/rest-api-reference/api-reference/site/get-all-site) and choose a Site to create resources in. Any Site where the Tenant +has an Allocation will be returned. +- Create a VPC using the [Create VPC endpoint](/infra-controller/rest-api-reference/api-reference/vpc/create-vpc). +- Retrieve available Site IP Blocks using the [Retrieve All IP Blocks endpoint](/infra-controller/rest-api-reference/api-reference/ip-block/get-all-ipblock). Any IP Block for which the Tenant has received +a Network Allocation from the Provider will be returned. +- Create a VPC Prefix or Subnet referencing the VPC and a Tenant IP Block +- Site supports Native Networking (FNN), create a VPC Prefix using the [Create VPC Prefix endpoint](/infra-controller/rest-api-reference/api-reference/vpc-prefix/create-vpc-prefix) +- Otherwise the user should create a Subnet using the [Create Subnet endpoint](/infra-controller/rest-api-reference/api-reference/subnet/create-subnet) +- Create an Operating System using the [Create Operating System endpoint](/infra-controller/rest-api-reference/api-reference/operating-system/create-operating-system) specifying iPXE script and user data. +- Retrieve available Instance Types using the [Retrieve All Instance Types endpoint](/infra-controller/rest-api-reference/api-reference/instance-type/get-all-instance-type). Any Instance Type for which +the Tenant has received a Compute Allocation from the Provider will be returned. +- Create an Instance specifying the VPC, VPC Prefix or Subnet, Operating System, and Instance Type diff --git a/fern/.gitignore b/fern/.gitignore index bad7ec53d0..9d58020ef8 100644 --- a/fern/.gitignore +++ b/fern/.gitignore @@ -1,3 +1,5 @@ .fern/ node_modules/ openapi/ai_examples_override.yml +package*.json +pnpm*.yaml \ No newline at end of file diff --git a/fern/README.md b/fern/README.md new file mode 100644 index 0000000000..0f3d613c79 --- /dev/null +++ b/fern/README.md @@ -0,0 +1,27 @@ +# NICo Fern Documentation + +This directory contains the documentation for the NICo Fern API. + +## Getting Started + +To develop Fern docs make sure you have the following tools installed: + +- Node.js v22 or later +- [Fern CLI](https://buildwithfern.com/learn/cli-api-reference/cli-reference/overview#install-fern-cli) +- [pnpm](https://pnpm.io/installation) + +## Local Development + +To start a local development server, run the following command: + +```bash +fern docs dev +``` + +This will start a local development server at `http://localhost:3000`. + +If you have trouble getting `esbuild` approved to install dependencies, you can try the following: + +```bash +PNPM_CONFIG_DANGEROUSLY_ALLOW_ALL_BUILDS=true fern docs dev +``` diff --git a/fern/docs.yml b/fern/docs.yml index a50b15a9d8..6ce5daea4c 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -67,7 +67,7 @@ css: navbar-links: - type: filled text: GitHub - href: https://github.com/NVIDIA/infra-controller-core + href: https://github.com/NVIDIA/infra-controller products: - display-name: NVIDIA Infra Controller @@ -88,6 +88,7 @@ redirects: destination: "infra-controller/documentation/getting-started/quick-start-guide" - source: "/infra-controller/documentation/getting-started/building-ni-co-containers" destination: "/infra-controller/documentation/getting-started/building-nico-containers" + experimental: mdx-components: - ./components diff --git a/fern/generators.yml b/fern/generators.yml index 4e098befd3..d8b67a3dcc 100644 --- a/fern/generators.yml +++ b/fern/generators.yml @@ -1,4 +1,3 @@ api: specs: - openapi: ../rest-api/openapi/spec.yaml - From 1ec167c47738d9b6aaa2385d3335be8b36978ff7 Mon Sep 17 00:00:00 2001 From: Tareque Hossain Date: Wed, 27 May 2026 09:36:44 -0700 Subject: [PATCH 2/2] Revise deprecation reference Signed-off-by: Tareque Hossain --- docs/openapi/getting_started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/openapi/getting_started.md b/docs/openapi/getting_started.md index 6c7d0031d3..71ac5c7a87 100644 --- a/docs/openapi/getting_started.md +++ b/docs/openapi/getting_started.md @@ -6,7 +6,7 @@ NICo REST `auth` module [README](https://github.com/NVIDIA/infra-controller-rest ### API Version The next step is to be aware of the API version being used. The API version can be retrieved by calling the [Retrieve Metadata endpoint](/infra-controller/rest-api-reference/api-reference/metadata/get-metadata). In general, the API maintains backward -compatibility with the previous versions. Any breaking changes are announced using a deprecation notice. Current and past deprecations are listed in the [Deprecations](/infra-controller/rest-api-reference/deprecations) section. +compatibility with the previous versions. Any breaking changes are announced using a deprecation notice. Click on each API resource to see the deprecation notices. ### Service Account Mode Depending on the auth configuration used, the NICo REST API may be configured in Service Account mode. In this mode, API users can act as both Provider and Tenant as part of the same organization.