Create a Custom Resource Definition and Verify it in the Kubernetes API

Scenario

Your team is building an internal platform that manages website configurations inside Kubernetes. Rather than storing these configs in ConfigMaps, the platform team wants a proper custom resource type — so operators can work with Website objects the same way they work with any built-in resource.

Your job is to register the Website custom resource type with the cluster, grant the default service account the RBAC permissions it needs to query the new endpoint, confirm the endpoint is live with curl, and save the response to disk for the platform audit trail.

Task

1. Create a CRD with the following specification:

   Field	Value
   Resource name (plural)	websites
   Resource name (singular)	website
   Short name	ws
   Group	apps.acme.com
   Version	v1
   Scope	Namespaced
   Kind	Website

   
   The v1 schema must accept these fields under spec:

   Field	Type	Required
   url	string	yes
   replicas	integer	no

2. Confirm the CRD is Established — meaning the API server has registered and activated the new resource type.
3. Create the following RBAC resources so the default service account in the default namespace can query the websites endpoint:
   • A ClusterRole named website-reader that grants get and list on websites in the apps.acme.com API group.
   • A ClusterRoleBinding named website-reader-binding that binds website-reader to the default service account in the default namespace.
4. Query the live API endpoint using curl and save the JSON response to /home/laborant/crd-live.json.

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: <plural>.<group>        # must match names.plural + spec.group exactly
spec:
  group: <group>
  scope: Namespaced
  names:
    plural: <plural>
    singular: <singular>
    shortNames:
      - <short>
    kind: <Kind>
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                # your fields here

kubectl describe crd websites.apps.acme.com

Type:    Established
Status:  True

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: website-reader
rules:
- apiGroups:
  - apps.acme.com
  resources:
  - websites
  verbs:
  - get
  - list
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: website-reader-binding
subjects:
- kind: ServiceAccount
  name: default
  namespace: default
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: website-reader

kubectl auth can-i list websites.apps.acme.com \
  --as=system:serviceaccount:default:default

TOKEN=$(kubectl create token default --duration=60s)

curl -sk \
  --header "Authorization: Bearer $TOKEN" \
  https://localhost:6443/apis/apps.acme.com/v1/websites \
  -o /home/laborant/crd-live.json

Understanding the Challenge

Kubernetes ships with a fixed set of resource types — Pods, Deployments, Services, and so on. But the API is designed to be extended. A CustomResourceDefinition (CRD) lets you teach Kubernetes about entirely new resource types that you define yourself.

Once a CRD is registered, the API server starts serving a new endpoint for that resource — and you can create, list, update, and delete instances of your custom type using the same tools and patterns as any built-in resource.

In this challenge you define a Website resource type, confirm the API server has activated it, grant the default service account permission to query the new endpoint via RBAC, and capture the live API response to disk.

What is a CustomResourceDefinition?

A CRD is a schema registration. It tells the Kubernetes API server:

• What the new resource is called (kind, plural, singular, shortName)
• Which API group and version it belongs to (group, version)
• Whether it is scoped to a namespace or cluster-wide (scope)
• What fields its spec may contain (openAPIV3Schema)

The CRD itself is stored in etcd under the apiextensions.k8s.io/v1 API group — which is why the manifest starts with apiVersion: apiextensions.k8s.io/v1.

You apply a CRD manifest
        │
        ▼
Kubernetes stores it in etcd
        │
        ▼
API server reads the CRD and registers a new endpoint:
  /apis/<group>/<version>/<plural>
        │
        ▼
You can now create/list/delete instances of your custom Kind

The Kubernetes API Structure

Every resource in Kubernetes lives under an API group. Built-in resources use either the core group (no prefix — v1) or named groups like apps/v1 and batch/v1. Custom resources always use a named group.

The URL structure for any resource is:

/apis/<group>/<version>/<plural>                    ← cluster-scoped
/apis/<group>/<version>/namespaces/<ns>/<plural>    ← namespace-scoped

For this challenge, with group apps.acme.com, version v1, and plural websites, the endpoint is:

/apis/apps.acme.com/v1/websites

Querying this with curl and getting 200 is proof the API server has accepted and is serving the new resource type.

CRD Lifecycle

manifest written
      │
      ▼
kubectl apply  ──→  CRD object created in etcd
      │
      ▼
API server controller processes the CRD
      │
      ├──→  NamesAccepted: True   (plural/singular names are unique)
      │
      └──→  Established: True     (endpoint is live and ready)

The Established condition is the signal that the new API endpoint is active. Until that condition is True, requests to the endpoint will return 404.

What is the openAPIV3Schema?

Every CRD in Kubernetes v1 must include a schema for validation. The schema uses the OpenAPI v3 format and defines what fields are allowed under spec, their types, and which are required.

For this challenge the schema is minimal:

openAPIV3Schema:
  type: object
  properties:
    spec:
      type: object
      required:
        - url
      properties:
        url:
          type: string
        replicas:
          type: integer

Without a schema, kubectl apply will reject the CRD manifest with a validation error.

Why RBAC is Required

Creating a CRD registers the new API endpoint — but it does not automatically grant anyone permission to use it.

Kubernetes enforces access control on every API request, including requests to custom resource endpoints. The default service account, which we use to generate the Bearer token for curl in Step 4, starts with no permissions by default.

Without RBAC:

curl → Bearer token (default SA) → API server
                                        │
                                        ▼
                               403 Forbidden
                        {"reason": "Forbidden", ...}

With RBAC (a ClusterRole + ClusterRoleBinding in place):

curl → Bearer token (default SA) → API server
                                        │
                                        ▼
                               200 OK  {"kind": "WebsiteList", ...}

The fix is two resources:

• A ClusterRole that defines what is allowed — get and list on websites in the apps.acme.com group.
• A ClusterRoleBinding that defines who gets those permissions — the default service account in the default namespace.

A ClusterRole (rather than a namespaced Role) is used here because the curl request hits the cluster-scoped list endpoint /apis/apps.acme.com/v1/websites, which spans all namespaces.

Step 1 : Write and Apply the CRD Manifest

Create and apply the CRD in a single step using cat and a here-doc piped directly into kubectl apply:

cat <<EOF | kubectl apply -f -
# A CRD registers a brand-new resource type with the Kubernetes API server.
# Once applied, the API server will start serving the /apis/apps.acme.com/v1/websites endpoint.
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  # metadata.name MUST be exactly "<plural>.<group>" — Kubernetes validates this
  # and will reject the manifest immediately if they don't match.
  name: websites.apps.acme.com
spec:
  # The API group this resource belongs to.
  # This becomes the first segment of the URL: /apis/apps.acme.com/...
  group: apps.acme.com

  # Namespaced means instances of Website live inside a namespace.
  # The alternative is Cluster, which makes them cluster-wide (like Nodes).
  scope: Namespaced

  names:
    plural: websites      # used in URLs:  /apis/apps.acme.com/v1/websites
    singular: website     # used by kubectl describe, get, etc.
    shortNames:
      - ws                # kubectl get ws  works as an alias
    kind: Website         # the Kind used in manifests: kind: Website

  versions:
    - name: v1
      served: true        # this version is active and the API server will serve it
      storage: true       # this version is stored in etcd (exactly one version must be true)
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              required:
                - url     # url is mandatory; replicas is optional
              properties:
                url:
                  type: string
                replicas:
                  type: integer
EOF

Expected output:

customresourcedefinition.apiextensions.k8s.io/websites.apps.acme.com created

Step 2 : Confirm the CRD is Established

After applying, check the CRD status:

kubectl get crd websites.apps.acme.com

NAME                     CREATED AT
websites.apps.acme.com   2026-07-20T10:00:00Z

For a more detailed view of the conditions:

kubectl describe crd websites.apps.acme.com

...
Conditions:
  Last Transition Time:  2026-07-20T10:00:01Z
  Message:               no conflicts found
  Reason:                NoConflicts
  Status:                True
  Type:                  NamesAccepted
  Last Transition Time:  2026-07-20T10:00:01Z
  Message:               the initial names have been accepted
  Reason:                InitialNamesAccepted
  Status:                True
  Type:                  Established
...

Both NamesAccepted and Established are True — the endpoint is live.

If Established is False:

• The metadata.name does not match <plural>.<group> — fix and reapply
• Another CRD is already using the same plural name — choose a different one

Step 3 : Create the RBAC Resources

There are two ways to do this. Use whichever fits your workflow.

Option A — kubectl create (imperative, fastest)

# Create the ClusterRole — defines what actions are allowed on which resource
kubectl create clusterrole website-reader \
  --verb=get,list \
  --resource=websites.apps.acme.com

# Bind the ClusterRole to the default service account in the default namespace
kubectl create clusterrolebinding website-reader-binding \
  --clusterrole=website-reader \
  --serviceaccount=default:default

Option B — cat | kubectl apply (declarative, full control)

cat <<EOF | kubectl apply -f -
# ClusterRole: defines the permission rules for the websites custom resource.
# We use a ClusterRole (not a Role) because the curl request targets the
# cluster-scoped list endpoint /apis/apps.acme.com/v1/websites.
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: website-reader
rules:
- apiGroups:
  - apps.acme.com       # must match the CRD's spec.group exactly
  resources:
  - websites            # must match the CRD's names.plural exactly
  verbs:
  - get                 # allows fetching a single Website by name
  - list                # allows listing all Websites — required for the curl endpoint
---
# ClusterRoleBinding: grants the ClusterRole to a specific subject.
# Here we bind it to the "default" service account in the "default" namespace,
# which is the account whose token we will use in the curl command.
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: website-reader-binding
subjects:
- kind: ServiceAccount
  name: default         # the service account name
  namespace: default    # the namespace the service account lives in
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: website-reader  # must match the ClusterRole name above
EOF

Expected output:

clusterrole.rbac.authorization.k8s.io/website-reader created
clusterrolebinding.rbac.authorization.k8s.io/website-reader-binding created

Verify the permission is active

# Ask Kubernetes whether the default service account can list websites
kubectl auth can-i list websites.apps.acme.com \
  --as=system:serviceaccount:default:default

yes

A response of yes confirms the RBAC binding is in place and the token we generate in Step 4 will be authorised to reach the endpoint.

Step 4 : Query the API and Save the Response

The Kubernetes API server requires authentication. Create a short-lived Bearer token for the default service account:

TOKEN=$(kubectl create token default --duration=10m)

Query the new endpoint and save the response directly to disk:

curl -sk \
  --header "Authorization: Bearer $TOKEN" \
  https://localhost:6443/apis/apps.acme.com/v1/websites \
  -o /home/laborant/crd-live.json

Inspect the saved file:

cat /home/laborant/crd-live.json

{
  "kind": "WebsiteList",
  "apiVersion": "apps.acme.com/v1",
  "metadata": {
    "resourceVersion": "1042"
  },
  "items": []
}

The response confirms:

• "kind": "WebsiteList" — the API server recognised the resource type
• "apiVersion": "apps.acme.com/v1" — the correct group and version
• "items": [] — no Website instances exist yet, which is expected

An empty items array is a successful result — the endpoint is live and returning a proper list response.

Why curl and Not kubectl?

kubectl is a high-level client — it handles auth, discovery, and serialisation for you. Querying the API directly with curl strips all of that away and proves the endpoint is genuinely registered at the HTTP level.

This matters in real operations: operators, monitoring tools, and CI pipelines often query the Kubernetes API directly over HTTP. Knowing how to construct and authenticate a raw API request is a core skill for anyone working with Kubernetes at the platform level.