NixOps4

https://nixops.dev
Admin
NixOps4 is a system in development that provides documentation for the core components of its...
Tokens:12,699
Snippets:243
Trust Score:5.4
Update:3 months ago
Show doc for...
Tokens:
Raw
### Local File Provider Example

Source: https://nixops.dev/manual/development/modules/index.html

An example of specifying a resource type from the `providers` module, using the local file provider.

```nix
__
providers.local.file

```

--------------------------------

### Example Resource Type from Providers Module

Source: https://nixops.dev/manual/development/modules

Illustrates how to reference a resource type from the `providers` module, specifically the `local.file` type.

```nix
providers.local.file
```

--------------------------------

### Example Resource Providers Declaration

Source: https://nixops.dev/manual/development/modules/index.html

Demonstrates how to declare resource providers, mapping local providers and external ones like 'foo'.

```nix
__
{
  local = inputs.nixops4.modules.nixops4Provider.local;
  foo = inputs.nixops4-resources-foo.modules.nixops4Provider.default;
}

```

--------------------------------

### Example Resource Provider Declaration

Source: https://nixops.dev/manual/development/modules

An example demonstrating how to declare resource providers, including local providers and providers from external NixOps modules.

```nix
{
  local = inputs.nixops4.modules.nixops4Provider.local;
  foo = inputs.nixops4-resources-foo.modules.nixops4Provider.default;
}
```

--------------------------------

### Define Resource and Composite Components

Source: https://nixops.dev/manual/development/modules

Example showing how to define a resource component with type and inputs, and a composite component with nested members.

```nix
__
members.webServer = {
  type = providers.local.exec;
  inputs.executable = "nginx";
};
members.database = {
  members.primary = { ... };
  members.replica = { ... };
};


```

--------------------------------

### Resource Provider Request and Response Example

Source: https://nixops.dev/manual/development/resource-provider/interface

Illustrates the JSON structure for a create resource request and its corresponding response in the NixOps resource provider protocol.

```json
{
  "createResourceRequest": {
    "type": "memo",
    "inputProperties": { "initialize_with": "hello" },
    "isStateful": true
  }
}

{
  "createResourceResponse": {
    "outputProperties": { "value": "hello" }
  }
}
```

--------------------------------

### Configuring State Providers

Source: https://nixops.dev/manual/development/state

State providers are configured using the 'state' attribute on stateful resources. This example shows how to define a 'state_file' provider and reference it.

```nix
{
  # Define the state provider resource
  members.myStateFile = {
    type = providers.local.state_file;
    inputs.name = "deployment-state.json";
  };

  # Use it for a stateful resource.
  # A generated unique ID (for example) will be stored in myStateFile.
  members.myReverseProxy = {
    type = providers.cloud.reverse_proxy;
    state = [ "myStateFile" ]; # References the state provider resource above
    inputs = {
      rules = [
        # ...
      ];
    };
  };
}
```

--------------------------------

### Stateless Resource Type Example

Source: https://nixops.dev/manual/development/resource-provider

Defines a 'file' resource type that does not require persistent state management between deployments. This is suitable for resources that are inherently stateless.

```nix
{
  resourceTypes.file = {
    description = "File on the local file system";
    requireState = false;
    inputs = { /* ... (options) */ };
    outputs = { /* ... (options) */ };
  };
}
```

--------------------------------

### Define PostgreSQL Database and User Resources

Source: https://nixops.dev/manual/development/concept/resource.html

Example of defining a PostgreSQL database resource and a user resource that depends on the database's output. This demonstrates a static dependency where one resource's output is used as another's input.

```nix
{
  members, ... }:
{
  members.database = {
    type = "postgresql_database";
    inputs.name = "myapp";
  };

  members.user = {
    type = "postgresql_user";
    inputs.database = members.database.outputs.name;
  };
}
```

--------------------------------

### Dynamic Structural Dependencies in NixOps

Source: https://nixops.dev/manual/development/concept/resource.html

Illustrates structural dependencies where the component graph topology depends on resource outputs. This example shows how a settings resource's outputs can dynamically define members within a clients attribute set.

```nix
{
  lib, members, ... }:
{
  members.settings = {
    imports = [ ./settings-resource.nix ];
    inputs.location = "https://panel.example.com/config.json";
  };

  members.clients.members =
    # Structural dependency: the members structure under clients depends on the outputs of the settings resource
    lib.mapAttrs
      (clientName: clientConfig: {
        imports = [ ./client.nix ];
        clientConfig = clientConfig;
      })
      members.settings.outputs.clients;

  members.shared.members = {
    # Static members here would not be structural dependencies
  }
  # This conditional member is also a structural dependency on the settings resource
  // lib.optionalAttrs members.settings.outputs.logging.enable {
    log_token = {
      # ...
    };
  };
}
```

--------------------------------

### Stateful Resource Type Example

Source: https://nixops.dev/manual/development/resource-provider

Defines a 'reverse_proxy' resource type that requires persistent state management. When 'requireState' is true, a 'state' handler must be configured for the resource.

```nix
{
  resourceTypes.reverse_proxy = {
    description = "Instance of a CloudTM managed reverse proxy";
    requireState = true;
    inputs = { /* ... (options) */ };
    outputs = { /* ... (options) */ };
  };
}
```

--------------------------------

### Create a basic resource

Source: https://nixops.dev/manual/development/resource-provider/testing

Use this command to create a simple resource like a file. Specify the provider executable, resource type, and input properties.

```bash
nixops4-resource-runner create \
  --provider-exe nixops4-resources-local \
  --type file \
  --input-str name test.txt \
  --input-str contents "Hello, world!"
```

--------------------------------

### Create a state file

Source: https://nixops.dev/manual/development/resource-provider/testing

Initialize a new state file for managing deployment state. This file will store resource and deployment information.

```bash
# Create a new state file
nixops4-resource-runner create \
  --provider-exe nixops4-resources-local \
  --type state_file \
  --input-str name "deployment-state.json"
```

--------------------------------

### Create a stateful resource

Source: https://nixops.dev/manual/development/resource-provider/testing

Create a resource that requires state persistence by using the `--stateful` flag. Initial state can be provided via JSON input.

```bash
# Create with state persistence
nixops4-resource-runner create \
  --provider-exe nixops4-resources-local \
  --type memo \
  --stateful \
  --input-json initialize_with '"initial value"'
```

--------------------------------

### Construct NixOps4 Root Component

Source: https://nixops.dev/manual/development/lib

Use `mkRoot` to transform a list of root component modules and other parameters into the format expected by the `nixops4` command. It also adds useful attributes.

```nix
__
{ modules, ... } -> nixops4Component

```

--------------------------------

### Evaluate Root Component Configuration

Source: https://nixops.dev/manual/development/lib

Use `evalRoot` to evaluate a root component configuration. This function is a building block for `mkRoot`, which is the typical entry point for defining the root.

```nix
__
EvalModulesArguments -> NixOpsArguments -> Configuration

```

--------------------------------

### nixops4-resource-runner create

Source: https://nixops.dev/manual/development/cli/nixops4-resource-runner

Creates a resource using a specified provider executable and resource type. Supports providing resource inputs via JSON or individual properties.

```APIDOC
## nixops4-resource-runner create

### Description
Create a resource

### Usage
`nixops4-resource-runner create [OPTIONS] --provider-exe <PROVIDER_EXE> --type <RESOURCE_TYPE>`

### Options
* `--provider-exe <PROVIDER_EXE>` - The executable that implements the resource operations.
* `--type <RESOURCE_TYPE>` - The type of resource to create: an identifier recognized by the resource provider.
* `--inputs-json <INPUT_PROPERTIES_JSON>` - The (whole) JSON input properties for the resource. This is a JSON object with the values needed to create the resource. The structure of this object is defined by the resource provider behavior.
* `-j`, `--input-json <NAME>` - An individual input property for the resource, in JSON format.
* `-s`, `--input-str <NAME>` - An individual input property for the resource, as a raw string. This is equivalent to `--input-json NAME JSON` if JSON is the JSON string formatting of STR.
* `--stateful` - Whether state persistence will be provided to the resource.
```

--------------------------------

### mkRoot

Source: https://nixops.dev/manual/development/lib/index.html

Transforms a list of root component modules and other parameters into the format expected by the `nixops4` command, and adds several useful attributes.

```APIDOC
## mkRoot

### Description
Turn a list of root component modules and some other parameters into the format expected by the `nixops4` command, and add a few useful attributes.

### Input Attributes
* `modules`: A list of modules to evaluate.
* `specialArgs`: A set of arguments to pass to the modules. These are available while `imports` are evaluated, but are not overridable or extensible, unlike the `_module.args` option.
* `prefix`: A list of strings representing the location of the root. Typical value: `[ "nixops4" ]`

### Output Attributes
* `_type`: `"nixops4Component"`
* `rootFunction`: Internal value for `nixops4` to use.
* `getProviders`: A function that returns a derivation for the providers of the root.
  * **Input Attributes**
    * `system`: The system for which to get the providers. Examples:
      * `"x86_64-linux"`
      * `"aarch64-darwin"`
  * **Output**
A derivation whose output references the providers for the root.
Note: Currently only collects providers defined at the root level. Providers defined in nested components are not included.
```

--------------------------------

### mkRoot

Source: https://nixops.dev/manual/development/lib

Transforms a list of root component modules and other parameters into the format expected by the `nixops4` command, and adds several useful attributes.

```APIDOC
## mkRoot

### Description
Turn a list of root component modules and some other parameters into the format expected by the `nixops4` command, and add a few useful attributes.

### Input Attributes
* `modules`: A list of modules to evaluate.
* `specialArgs`: A set of arguments to pass to the modules. These are available while `imports` are evaluated, but are not overridable or extensible, unlike the `_module.args` option.
* `prefix`: A list of strings representing the location of the root. Typical value: `[ "nixops4" ]`

### Output Attributes
* `_type`: `"nixops4Component"`
* `rootFunction`: Internal value for `nixops4` to use.
* `getProviders`: A function that returns a derivation for the providers of the root.
  **Input attributes**
    * `system`: The system for which to get the providers. Examples:
      * `"x86_64-linux"`
      * `"aarch64-darwin"`
  **Output**
A derivation whose output references the providers for the root.
Note: Currently only collects providers defined at the root level. Providers defined in nested components are not included.
```

--------------------------------

### Default Command Line Arguments

Source: https://nixops.dev/manual/development/modules

Specifies the default empty list for command line arguments to pass to the resource provider executable.

```nix
[
  
]
```

--------------------------------

### Generate Provider Documentation

Source: https://nixops.dev/manual/development/lib

Use `renderProviderDocs` to generate markdown documentation for a NixOps4 provider module. This function renders documentation for all resource types, including their inputs and outputs.

```nix
renderProviderDocs {
  system = "x86_64-linux";
  module = self.modules.nixops4Provider.local;
}

```

--------------------------------

### renderProviderDocs

Source: https://nixops.dev/manual/development/lib

Generates markdown documentation for a NixOps4 provider module, detailing all resource types, their inputs, and outputs.

```APIDOC
## renderProviderDocs

### Description
Generate documentation for a NixOps4 provider module.
This function renders markdown documentation for all resource types defined in a provider module, including their inputs and outputs.

### Arguments
* `system`: The system string (e.g., “x86_64-linux”)
* `module`: A NixOps4 provider module containing resource type definitions and documentation metadata (`name`, `description`, `sourceBaseUrl`, `sourceName`)

### Example
```
renderProviderDocs {
  system = "x86_64-linux";
  module = self.modules.nixops4Provider.local;
}
```

### Type
```
renderProviderDocs :: {
  system :: String,
  module :: NixModule
} -> Derivation
```

The resulting derivation contains markdown files for each resource type plus an index.md file. The files use mdBook-compatible includes for option documentation.
```

--------------------------------

### Default Arguments for Local Exec

Source: https://nixops.dev/manual/development/providers/local/exec

The default value for the 'args' attribute, which is an empty list.

```nix
__
[

]

```

--------------------------------

### evalRoot

Source: https://nixops.dev/manual/development/lib

Evaluates a root component configuration. This function serves as a building block for `mkRoot`, which is typically used as the entry point for defining the root configuration.

```APIDOC
## evalRoot

### Description
Evaluate a root component configuration. This is a building block for `mkRoot`, which is the usual entry point for defining the root.

### Arguments
Arguments for evalModules - i.e. the Module System. These are adjusted to include NixOps-specific arguments.
Arguments provided by NixOps. These provide the context of the component, including the resource outputs.

### Output
The return value is a Module System `configuration`, including attributes such as `config` and `options`.
```

--------------------------------

### Read current state from state file

Source: https://nixops.dev/manual/development/resource-provider/testing

Retrieve the current state of deployments and resources from a state file. Initially, this will reflect an empty state.

```bash
# Read the current state
nixops4-resource-runner state-read \
  --provider-exe nixops4-resources-local \
  --type state_file \
  --inputs-json '{"name": "deployment-state.json"}' \
  --outputs-json '{}'
```

--------------------------------

### Create Resource Request Schema

Source: https://nixops.dev/manual/development/schema/resource-v0

Defines the structure for creating a resource, including its path and content.

```json
{
  "type": "file",
  "inputProperties": {
    "path": "pubkey.txt",
    "content": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQD"
  },
  "isStateful": false
}
```

--------------------------------

### nixops4-resource-runner state-event

Source: https://nixops.dev/manual/development/cli/nixops4-resource-runner

Sends a state event to a stateful resource. Includes details about the event, NixOps version, and any state patches.

```APIDOC
## nixops4-resource-runner state-event

### Description
Send a state event to a state resource

### Usage
`nixops4-resource-runner state-event --provider-exe <PROVIDER_EXE> --type <RESOURCE_TYPE> --inputs-json <INPUT_PROPERTIES_JSON> --outputs-json <OUTPUT_PROPERTIES_JSON> --event <EVENT> --nixops-version <NIXOPS_VERSION> --patch-json <PATCH_JSON>`

### Options
* `--provider-exe <PROVIDER_EXE>` - The executable that implements the resource operations.
* `--type <RESOURCE_TYPE>` - The type of resource to send the event to: an identifier recognized by the resource provider.
* `--inputs-json <INPUT_PROPERTIES_JSON>` - The JSON input properties for the resource.
* `--outputs-json <OUTPUT_PROPERTIES_JSON>` - The JSON output properties for the resource.
* `--event <EVENT>` - The operation that produced this change.
* `--nixops-version <NIXOPS_VERSION>` - The version of NixOps that produced this event.
* `--patch-json <PATCH_JSON>` - JSON Patch operations to apply to the state.
```

--------------------------------

### Default Resource Providers

Source: https://nixops.dev/manual/development/modules

Defines the default empty attribute set for resource providers.

```nix
{
}
```

--------------------------------

### Update a stateful resource

Source: https://nixops.dev/manual/development/resource-provider/testing

Update an existing stateful resource by providing new inputs and the previous inputs and outputs. This ensures correct state transitions.

```bash
# Update the stateful resource
nixops4-resource-runner update \
  --provider-exe nixops4-resources-local \
  --type memo \
  --inputs-json '{"initialize_with": "new value"}' \
  --previous-inputs-json '{"initialize_with": "initial value"}' \
  --previous-outputs-json '{"value": "initial value"}'
```

--------------------------------

### NixOps State Schema

Source: https://nixops.dev/manual/development/schema/state-v0

This is the basic structure of a NixOps state file, defining the top-level properties for resources and deployments.

```json
{
  "_type": "nixopsState",
  "resources": {},
  "deployments": {}
}
```

--------------------------------

### nixops4-resource-runner state-read

Source: https://nixops.dev/manual/development/cli/nixops4-resource-runner

Reads the state from a stateful resource. Requires the provider executable, resource type, and input/output properties.

```APIDOC
## nixops4-resource-runner state-read

### Description
Read state from a state resource

### Usage
`nixops4-resource-runner state-read --provider-exe <PROVIDER_EXE> --type <RESOURCE_TYPE> --inputs-json <INPUT_PROPERTIES_JSON> --outputs-json <OUTPUT_PROPERTIES_JSON>`

### Options
* `--provider-exe <PROVIDER_EXE>` - The executable that implements the resource operations.
* `--type <RESOURCE_TYPE>` - The type of resource to read state from: an identifier recognized by the resource provider.
* `--inputs-json <INPUT_PROPERTIES_JSON>` - The JSON input properties for the resource.
* `--outputs-json <OUTPUT_PROPERTIES_JSON>` - The JSON output properties for the resource.
```

--------------------------------

### Type Signature for renderProviderDocs

Source: https://nixops.dev/manual/development/lib

The type signature for the `renderProviderDocs` function, indicating it takes system and module arguments and returns a Derivation.

```nix
renderProviderDocs :: {
  system :: String,
  module :: NixModule
} -> Derivation

```

--------------------------------

### Default State Handler Value

Source: https://nixops.dev/manual/development/modules

The default value for a resource's state handler is null, indicating no specific handler is configured.

```nix
null
```

--------------------------------

### Resource Output Properties Schema

Source: https://nixops.dev/manual/development/schema/resource-v0

Defines the structure for output properties of a resource, including its ID and network interfaces.

```json
{
  "outputProperties": {
    "id": "vm-12w94ty8",
    "interfaces": {
      "eth0": {
        "ipv4": "198.51.100.11"
      }
    }
  }
}
```

--------------------------------

### State File Event Structure

Source: https://nixops.dev/manual/development/state

The state file contains a sequence of JSON objects, each representing a state event. These events use JSON Patch operations to record incremental changes.

```json
{
  "index": 0,
  "meta": {
    "time": "2024-01-01T00:00:00Z"
  },
  "patch": [
    {
      "op": "add",
      "path": "",
      "value": {
        "_type": "nixopsState",
        "resources": {},
        "deployments": {}
      }
    }
  ]
}
{
  "index": 1,
  "meta": {
    "time": "2024-01-01T00:01:00Z",
    "event": "create"
  },
  "patch": [
    {
      "op": "add",
      "path": "/resources/myfile",
      "value": {
        "type": "file",
        "inputProperties": {"name": "test.txt", "contents": "hello"},
        "outputProperties": {}
      }
    }
  ]
}
```

--------------------------------

### nixops4-resource-runner update

Source: https://nixops.dev/manual/development/cli/nixops4-resource-runner

Updates a stateful resource. Requires the provider executable, resource type, new inputs, and previous state information.

```APIDOC
## nixops4-resource-runner update

### Description
Update a stateful resource

### Usage
`nixops4-resource-runner update --provider-exe <PROVIDER_EXE> --type <RESOURCE_TYPE> --inputs-json <INPUT_PROPERTIES_JSON> --previous-inputs-json <PREVIOUS_INPUT_PROPERTIES_JSON> --previous-outputs-json <PREVIOUS_OUTPUT_PROPERTIES_JSON>`

### Options
* `--provider-exe <PROVIDER_EXE>` - The executable that implements the resource operations.
* `--type <RESOURCE_TYPE>` - The type of resource to update: an identifier recognized by the resource provider.
* `--inputs-json <INPUT_PROPERTIES_JSON>` - The new JSON input properties for the resource. This is a JSON object with the values needed to update the resource. The structure of this object is defined by the resource provider behavior.
* `--previous-inputs-json <PREVIOUS_INPUT_PROPERTIES_JSON>` - The previous JSON input properties for the resource, as recorded in the state.
* `--previous-outputs-json <PREVIOUS_OUTPUT_PROPERTIES_JSON>` - The previous JSON output properties for the resource, as recorded in the state.
```

--------------------------------

### Default Communication Type

Source: https://nixops.dev/manual/development/modules

Sets the default communication type to 'stdio' for interacting with the resource provider executable.

```nix
"stdio"
```

--------------------------------

### Default Value for Stdin Input

Source: https://nixops.dev/manual/development/providers/local/exec

The default value for the 'input' attribute, which is null, indicating no standard input is provided to the command.

```nix
__
null


```

--------------------------------

### Manage state file with JSON Patch operations

Source: https://nixops.dev/manual/development/resource-provider/testing

Apply JSON Patch operations to modify the state file, enabling creation, update, and deletion of resources. This provides an audit trail of changes.

```bash
# Add a resource to the state
nixops4-resource-runner state-event \
  --provider-exe nixops4-resources-local \
  --type state_file \
  --inputs-json '{"name": "deployment-state.json"}' \
  --outputs-json '{}' \
  --event "create" \
  --nixops-version "4.0.0" \
  --patch-json '[
    {
      "op": "add",
      "path": "/resources/myfile",
      "value": {
        "type": "file",
        "inputProperties": {"name": "test.txt", "contents": "hello"},
        "outputProperties": {}
      }
    }
  ]'

# Update a resource in the state
nixops4-resource-runner state-event \
  --provider-exe nixops4-resources-local \
  --type state_file \
  --inputs-json '{"name": "deployment-state.json"}' \
  --outputs-json '{}' \
  --event "update" \
  --nixops-version "4.0.0" \
  --patch-json '[
    {
      "op": "replace",
      "path": "/resources/myfile/inputProperties/contents",
      "value": "updated content"
    }
  ]'

# Remove a resource from the state
nixops4-resource-runner state-event \
  --provider-exe nixops4-resources-local \
  --type state_file \
  --inputs-json '{"name": "deployment-state.json"}' \
  --outputs-json '{}' \
  --event "destroy" \
  --nixops-version "4.0.0" \
  --patch-json '[
    {
      "op": "remove",
      "path": "/resources/myfile"
    }
  ]'
```

--------------------------------

### Default Value for Create-Only Execution

Source: https://nixops.dev/manual/development/providers/local/exec

The default value for the 'createOnly' attribute, which is false, meaning the command executes on both create and update.

```nix
__
false


```

--------------------------------

### Resolved State Structure

Source: https://nixops.dev/manual/development/state

After adding resources, the state can be read and resolved to this structure, which follows the NixOps4 state schema.

```json
{
  "_type": "nixopsState",
  "resources": {
    "myfile": {
      "type": "file",
      "inputProperties": {
        "name": "test.txt",
        "contents": "hello"
      },
      "outputProperties": {}
    }
  },
  "deployments": {}
}
```
Tokens:
Raw