crossplane / crossplane/docs

Document the Crossplane project file (and the new pre-built function and per-language schema options)

Open
#1,106 0 comments 0 reactions 0 assignees View on GitHub
content request
Dominant language
SCSS
Stars
60
Forks
163
Avg merge
15h 20m
Merged PRs (30d)
9

Description

### What's Missing?

The Crossplane CLI's project workflow (`crossplane project init`/`build`/`run`) is configured by a project file — a `Project` resource whose `spec` (`ProjectSpec`) controls the repository, dependencies, paths, target architectures, embedded functions, and schema generation. Today this file has no prose documentation. The only place any of it surfaces is the auto-generated [CLI command reference](https://docs.crossplane.io/master/cli/command-reference/), which documents command flags but not the project file's schema. The packaging docs ([Configurations](https://docs.crossplane.io/master/packages/configurations/)) only cover the older `crossplane xpkg build` + `crossplane.yaml` flow, not the newer Projects flow.

crossplane/cli#24 just merged and adds two new optional `ProjectSpec` fields that need documenting:

**1. Pre-built function runtimes** (`spec.functions`) — fixes crossplane/cli#21. An explicit list of functions to build, which disables the default per-subdirectory auto-discovery. Each entry uses a `source` discriminator (`Directory` or `Tarball`). `Tarball` sources skip language detection and load a pre-built single-platform OCI image tarball per target architecture (`-.tar`/`.tar.gz`), so projects can build functions with their own toolchain (make, Nix, Bazel, `ko`, `docker save`, etc.).

```yaml
spec:
architectures: [amd64, arm64]
functions:
- source: Directory
directory:
name: function-a
- source: Tarball
tarball:
name: function-b
pathPrefix: build/function-b
```

**2. Per-language schema generation** (`spec.schemas.languages`) — fixes crossplane/cli#29. Restricts schema generation to a subset of the supported languages (Go, JSON, KCL, Python) instead of generating all four. Applies to both the project's own XRDs and its dependencies, and flows through `project build`/`run` and `dependency update-cache`/`clean-cache`.

```yaml
spec:
schemas:
languages: [python]
```

Ideally these are documented as part of a broader project-file reference page rather than in isolation, since the project file itself is currently undocumented.

Note the CLI docs are mid-restructure (crossplane/docs#1104 moves them into their own versioned tree and gives them a separate sidebar/version menu), so placement should account for that.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.