1 Registries
Kumori DSL supports the use of custom registries to host and distribute modules. By default, kdsl uses the official Kumori registry to resolve dependencies, but you can configure additional registries as needed using the kdsl registry command.
When a dependency is added, kdsl will search the configured registries in order to locate and download the specified module, making it easy to manage dependencies from multiple sources.
Assume your kumori.mod.json has the following content:
We can see that we have a dependency on the module example.com/remote/module with version v1.2.3.
The process to resolve this dependency would be as follows: 1. Check the local registries (configured via the kdsl registry command) 2. If not found, the target URL is assumed to be a direct link to the module repository, where the actual contents are located. 3. If an entry in the local registries is found for the example.com prefix, it will attempt to download the corresponding index file from the specified URL in the registry. 4. Once the index file has been fetched, it will look for the module remote/module and the specified version v1.2.3 entry. When found, it will point to the actual location of the module source code.
The index file is stored in a global cache located at .config/kdsl/cache/<registry-name>/index.json, to avoid fetching it multiple times.
The previous example assumes that you have included a registry, named example.com, pointing to a custom URL, with the following command.
After running this command, the kdsl tool will store the registry configuration locally, adding an entry similar to this in the configuration file located at ~/.config/kdsl/registries.json:
[!NOTE] The
selectorfield is not limited to domain names. You can use any string as a selector, as long as it matches the prefix of the module names you want to resolve using that registry.
This would configure a registry named example.com that points to the URL https://example.com/registry, where the index file can be found. The index file hosted at https://example.com/registry/index.json, which therefore assumes that this URL is accesible and downloadable. It would look like this:
1.1 Building your own index file
You are completely free to build your own index file, as long as it follows a concrete structure, specified to allow kdsl to parse and understand it. You can place your index.json file anywhere you want, as long as it is accessible via HTTP(S). Refer to the command kdsl index for more details on index management.
The structure of the index file must follow this schema:
{
"modules": [
{
"domain": "string", // The domain of the module (e.g., "kumori.systems/jenkins")
"version": "string", // The semantic version of the module (e.g., "1.0.0")
"location": "string", // The URL of the module repository (e.g., "https://gitlab.com/kumori/people/fdominguez/components/jenkins")
"checksum": "h1:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", // The SHA-256 checksum of the module package, prefixed with h1:
"description": "string", // (Optional) A brief description of the module
"releaseDate": "DD-MM-YYYY", // (Optional) Release date in DD-MM-YYYY format
"artifacts": [
{
"name": "string", // Name of the artifact
"description": "string", // (Optional) Description of the artifact
"marketplace": true, // Whether this artifact is available in the marketplace
"type": "component", // Type of artifact ("component" or "service")
"schema": {}, // JSON Schema object describing the artifact
"location": "string", // Relative path or URL to the artifact
"icon": "string", // (Optional) Filename for the artifact's icon
"categories": [ "string" ], // (Optional) Categories for this artifact (can be empty)
"tags": [ "string" ] // (Optional) Tags for this artifact (can be empty)
}
// ... more artifacts ...
]
}
// ... more modules ...
]
}The index file is validated on download against a JSON Schema to ensure correctness. This is the schema:
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://kumori.systems/kdsl/registry-index.schema.json",
"title": "KDSL Registry Module Index",
"description": "Defines the structure of the index.json file hosted in a registry repository.",
"$defs": {
"role": {
"type": "object",
"required": ["name", "type", "roles"],
"properties": {
"name": {
"type": "string",
"description": "Role name"
},
"type": {
"type": "string",
"enum": ["component", "service"],
"description": "Type of the role"
},
"roles": {
"type": "array",
"minItems": 0,
"items": { "$ref": "#/$defs/role" },
"description": "Nested roles (for service roles)"
}
},
"additionalProperties": false
}
},
"type": "object",
"required": ["modules"],
"properties": {
"modules": {
"type": "array",
"minItems": 0,
"uniqueItems": true,
"description": "List of modules available in this registry index",
"items": {
"type": "object",
"required": ["domain", "version", "location", "checksum", "artifacts"],
"properties": {
"domain": {
"type": "string",
"description": "Domain of the module (e.g. kumori.systems/jenkins)"
},
"version": {
"type": "string",
"description": "Semantic version of the module"
},
"description": {
"type": "string",
"description": "Optional human-readable module description"
},
"location": {
"type": "string",
"description": "Location (URL) where the module resides"
},
"releaseDate": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Release date in YYYY-MM-DD format"
},
"checksum": {
"type": "string",
"pattern": "^h1:[a-fA-F0-9]{64}$",
"description": "SHA-256 checksum of the module, prefixed with h1:"
},
"artifacts": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"required": ["name", "type", "marketplace", "schema", "location"],
"properties": {
"name": {
"type": "string",
"description": "Name of the artifact"
},
"description": {
"type": "string",
"description": "Optional human-readable artifact description"
},
"requirements": {
"type": "object",
"description": "Requirements for using this artifact",
"properties": {
"cpu": {
"type": "number",
"description": "Minimum vCPUs required"
},
"memory": {
"type": "number",
"description": "Minimum memory (in GB) required"
}
}
},
"marketplace": {
"type": "boolean",
"description": "Whether this artifact is available in the marketplace"
},
"type": {
"type": "string",
"enum": ["component", "service"],
"description": "Type of artifact"
},
"schema": {
"type": "object",
"description": "JSON Schema object describing the artifact"
},
"location": {
"type": "string",
"description": "Relative path or URL to the artifact"
},
"roles": {
"type": "array",
"minItems": 0,
"items": { "$ref": "#/$defs/role" },
"description": "List of roles exposed by this artifact"
},
"icon": {
"type": "string",
"description": "Filename for the artifact's icon"
},
"categories": {
"type": "array",
"items": { "type": "string" },
"description": "Categories for this artifact"
},
"tags": {
"type": "array",
"items": { "type": "string" },
"description": "Tags for this artifact"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}