Plugin¶

The Plugin CRD defines a Minecraft plugin to be installed on matched servers.

Overview¶

apiVersion: mc.k8s.lex.la/v1alpha1
kind: Plugin
metadata:
  name: essentialsx
  namespace: minecraft
spec:
  source:
    type: hangar
    project: "EssentialsX/Essentials"
  updateStrategy: "latest"
  instanceSelector:
    matchLabels:
      environment: production

Spec Fields¶

source¶

Required — Defines where to fetch the plugin.

Field	Description
`type`	Repository type (see supported sources below)
`project`	Plugin identifier (for hangar)
`url`	Direct download URL (planned)

spec:
  source:
    type: hangar
    project: "EssentialsX/Essentials"

Supported Sources

Currently implemented:

hangar — PaperMC Hangar (hangar.papermc.io)

Planned (not yet implemented):

modrinth — #2
spigot — #3
url — #4

updateStrategy¶

Optional — Defines how plugin versions are managed. Default: latest.

Value	Description
`latest`	Always use newest version from repository
`auto`	Constraint solver picks best version compatible with servers
`pin`	Pin to specific version (requires `version` field)
`build-pin`	Pin to specific version and build

spec:
  updateStrategy: "latest"

version¶

Optional — Target plugin version. Required for pin and build-pin strategies.

spec:
  updateStrategy: "pin"
  version: "2.20.1"

build¶

Optional — Target build number. Only used with build-pin strategy.

spec:
  updateStrategy: "build-pin"
  version: "2.20.1"
  build: 456

updateDelay¶

Optional — Grace period before applying new plugin versions.

spec:
  updateDelay: "72h"  # Wait 3 days before using new releases

instanceSelector¶

Required — Label selector to match PaperMCServer instances.

spec:
  instanceSelector:
    matchLabels:
      environment: production
      server-type: survival

Or with expressions:

spec:
  instanceSelector:
    matchExpressions:
      - key: environment
        operator: In
        values:
          - production
          - staging

port¶

Optional — Network port exposed by the plugin. Added to matched servers' Services.

Useful for plugins with web interfaces (Dynmap, BlueMap, Plan).

spec:
  port: 8123  # Dynmap web interface

Port Handling

The port is added as both TCP and UDP to the Service. Port name format: plugin-{pluginname}

compatibilityOverride¶

Optional — Manual compatibility specification for plugins without proper metadata.

Field	Description
`enabled`	Enable the override
`minecraftVersions`	List of compatible Minecraft versions

spec:
  compatibilityOverride:
    enabled: true
    minecraftVersions:
      - "1.20.4"
      - "1.20.6"
      - "1.21.1"

Use Sparingly

Only use compatibility overrides when the plugin repository lacks version metadata. Incorrect overrides may cause plugin compatibility issues.

Status Fields¶

availableVersions¶

Cached metadata from the plugin repository.

status:
  availableVersions:
    - version: "2.21.0"
      minecraftVersions:
        - "1.20.4"
        - "1.21.1"
      downloadURL: "https://..."
      hash: "sha256:abc123..."
      cachedAt: "2024-01-15T10:00:00Z"
      releasedAt: "2024-01-10T12:00:00Z"

matchedInstances¶

Servers matched by the instanceSelector.

status:
  matchedInstances:
    - name: survival
      namespace: minecraft
      version: "1.21.4"
      compatible: true
    - name: creative
      namespace: minecraft
      version: "1.20.4"
      compatible: true

repositoryStatus¶

Plugin repository availability.

Value	Description
`available`	Repository accessible, metadata current
`unavailable`	Repository temporarily unreachable
`orphaned`	Repository removed, using cached data

lastFetched¶

Timestamp of the last successful API fetch.

status:
  lastFetched: "2024-01-15T10:00:00Z"

conditions¶

Standard Kubernetes conditions.

Type	Description
`Ready`	Plugin is ready and compatible
`MetadataFetched`	Repository metadata is available
`Compatible`	Plugin is compatible with all matched servers

Complete Example¶

apiVersion: mc.k8s.lex.la/v1alpha1
kind: Plugin
metadata:
  name: bluemap
  namespace: minecraft
spec:
  source:
    type: hangar
    project: "BlueMap/BlueMap"

  updateStrategy: "latest"
  updateDelay: "168h"  # Wait 7 days

  # Match all production servers
  instanceSelector:
    matchLabels:
      environment: production

  # Expose BlueMap web interface
  port: 8100

---
apiVersion: mc.k8s.lex.la/v1alpha1
kind: Plugin
metadata:
  name: essentialsx
  namespace: minecraft
spec:
  source:
    type: hangar
    project: "EssentialsX/Essentials"

  updateStrategy: "pin"
  version: "2.20.1"

  instanceSelector:
    matchLabels:
      environment: production

---
apiVersion: mc.k8s.lex.la/v1alpha1
kind: Plugin
metadata:
  name: worldedit
  namespace: minecraft
spec:
  source:
    type: hangar
    project: "EngineHub/WorldEdit"

  updateStrategy: "auto"

  instanceSelector:
    matchExpressions:
      - key: server-type
        operator: In
        values:
          - creative
          - build

Plugin Deletion¶

When a Plugin is deleted:

The operator marks the plugin for deletion on matched servers
During next server restart, the JAR file is removed from /data/plugins/
Once all JARs are cleaned up, the Plugin resource is fully deleted

Check deletion progress:

kubectl get plugin essentialsx -o yaml

status:
  deletionProgress:
    - serverName: survival
      namespace: minecraft
      jarDeleted: true
      deletedAt: "2024-01-15T04:00:00Z"
    - serverName: creative
      namespace: minecraft
      jarDeleted: false