diff --git a/README.md b/README.md
index 2e20d6a3..231a8865 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,18 @@
 # Custom Metrics Adapter Server Boilerplate
 
+[![Go Reference](https://pkg.go.dev/badge/sigs.k8s.io/custom-metrics-apiserver.svg)](https://pkg.go.dev/sigs.k8s.io/custom-metrics-apiserver)
+
 ## Purpose
 
 This repository contains boilerplate code for setting up an implementation
-of the custom metrics API (https://github.com/kubernetes/metrics).
+of the [Metrics APIs](https://github.com/kubernetes/metrics):
+
+- Custom metrics (`k8s.io/metrics/pkg/apis/custom_metrics`)
+- External metrics (`k8s.io/metrics/pkg/apis/external_metrics`)
 
 It includes the necessary boilerplate for setting up an implementation
 (generic API server setup, registration of resources, etc), plus an
-implementation for testing that allows setting metric values over HTTP.
+implementation for testing that allows setting custom metric values over HTTP.
 
 ## How to use this repository
 
@@ -22,60 +27,62 @@ More information can be found in the [getting started
 guide](/docs/getting-started.md), and the testing implementation can be
 found in the [test-adapter directory](/test-adapter).
 
-## Development for boilerplate project
-
-### Pre-reqs
+### Prerequisites
 
-- [Go](https://golang.org/doc/install) same version of [Go as Kubernetes](https://github.com/kubernetes/community/blob/master/contributors/devel/development.md#go)
-- [git](https://git-scm.com/downloads)
+[Go](https://go.dev/doc/install): this library requires the same version of
+[Go as Kubernetes](https://git.k8s.io/community/contributors/devel/development.md#go).
 
-### Clone and Build the Testing Adapter
+## Test Adapter
 
 There is a test adapter in this repository that can be used for testing
 changes to the repository, as a mock implementation of the APIs for
 automated unit tests, and also as an example implementation.
 
-Note that this adapter *should not* be used for production.  It's for
+Note that this adapter **should not** be used for production.  It's for
 writing automated e2e tests and serving as a sample only.
 
 To build and deploy it:
 
 ```bash
-# build the test-adapter container as $REGISTRY/k8s-test-metrics-adapter
+# build the test-adapter container as $REGISTRY/k8s-test-metrics-adapter-amd64
 export REGISTRY=<some-prefix>
 make test-adapter-container
 
 # push the container up to a registry (optional if your cluster is local)
-docker push $REGISTRY/k8s-test-metrics-adapter
+docker push $REGISTRY/k8s-test-metrics-adapter-amd64
 
-# launch the adapter using the test adapter deployment files
+# launch the adapter using the test adapter deployment manifest
 kubectl apply -f test-adapter-deploy/testing-adapter.yaml
 ```
 
-After the deployment you can set new metrics on the adapter using
-query the testing adapter with:
+When the deployment is ready, you can define new metrics on the test adapter
+by querying the write endpoint:
 
 ```bash
-# set up a proxy to the api server so we can access write endpoints
+# set up a proxy to the API server so we can access write endpoints
 # of the testing adapter directly
 kubectl proxy &
 # write a sample metric -- the write paths match the same URL structure
 # as the read paths, but at the /write-metrics base path.
 # data needs to be in json, so we also need to set the content-type header
-curl -XPOST -H 'Content-Type: application/json' http://localhost:8001/api/v1/namespaces/custom-metrics/services/custom-metrics-apiserver:http/proxy/write-metrics/namespaces/default/services/kubernetes/test-metric --data-raw '"300m"'
+curl -X POST \
+  -H 'Content-Type: application/json' \
+  http://localhost:8001/api/v1/namespaces/custom-metrics/services/custom-metrics-apiserver:http/proxy/write-metrics/namespaces/default/services/kubernetes/test-metric \
+  --data-raw '"300m"'
 ```
 
 ```bash
 # you can pipe to `jq .` to pretty-print the output, if it's installed
 # (otherwise, it's not necessary)
-kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta1" | jq .
+kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta2" | jq .
 # fetching certain custom metrics of namespaced resources
-kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta1/namespaces/default/services/kubernetes/test-metric" | jq .
+kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta2/namespaces/default/services/kubernetes/test-metric" | jq .
 ```
 
 If you wanted to target a simple nginx-deployment and then use this as an HPA scaler metric, something like this would work following the previous curl command:
-```
-apiVersion: autoscaling/v2beta2
+
+```yaml
+apiVersion: autoscaling/v2
 kind: HorizontalPodAutoscaler
 metadata:
   name: nginx-deployment
@@ -101,6 +108,14 @@ spec:
         value: 300m
 ```
 
+You can also query the external metrics:
+
+```bash
+kubectl get --raw "/apis/external.metrics.k8s.io/v1beta1" | jq .
+# fetching certain custom metrics of namespaced resources
+kubectl get --raw "/apis/external.metrics.k8s.io/v1beta1/namespaces/default/my-external-metric" | jq .
+```
+
 ## Compatibility
 
 The APIs in this repository follow the standard guarantees for Kubernetes
@@ -108,15 +123,13 @@ APIs, and will follow Kubernetes releases.
 
 ## Community, discussion, contribution, and support
 
-Learn how to engage with the Kubernetes community on the [community
-page](http://kubernetes.io/community/).
+Learn how to engage with the Kubernetes community on the
+[community page](https://kubernetes.io/community/).
 
 You can reach the maintainers of this repository at:
 
-- Slack: #sig-instrumentation (on https://kubernetes.slack.com -- get an
-  invite at slack.kubernetes.io)
-- Mailing List:
-  https://groups.google.com/forum/#!forum/kubernetes-sig-instrumentation
+- [Slack](https://slack.k8s.io/): channel `#sig-instrumentation`
+- [Mailing List](https://groups.google.com/g/kubernetes-sig-instrumentation)
 
 ### Code of Conduct
 
diff --git a/test-adapter-deploy/testing-adapter.yaml b/test-adapter-deploy/testing-adapter.yaml
index 28848bf3..3bacf2c0 100644
--- a/test-adapter-deploy/testing-adapter.yaml
+++ b/test-adapter-deploy/testing-adapter.yaml
@@ -133,6 +133,20 @@ spec:
   groupPriorityMinimum: 100
   versionPriority: 200
 ---
+apiVersion: apiregistration.k8s.io/v1
+kind: APIService
+metadata:
+  name: v1beta1.external.metrics.k8s.io
+spec:
+  service:
+    name: custom-metrics-apiserver
+    namespace: custom-metrics
+  group: external.metrics.k8s.io
+  version: v1beta1
+  insecureSkipTLSVerify: true
+  groupPriorityMinimum: 100
+  versionPriority: 100
+---
 apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRole
 metadata: