# kubectl Usage Conventions

LLMS index: [llms.txt](/llms.txt)

---

<!-- overview -->
Recommended usage conventions for `kubectl`.


<!-- body -->

## Using `kubectl` in Reusable Scripts

For a stable output in a script:

* Request one of the machine-oriented output forms, such as `-o name`, `-o json`, `-o yaml`, `-o go-template`, or `-o jsonpath`.
* Fully-qualify the version. For example, `jobs.v1.batch/myjob`. This will ensure that kubectl does not use its default version that can change over time.
* Don't rely on context, preferences, or other implicit states.

## Subresources

* You can use the `--subresource` argument for kubectl subcommands such as `get`, `patch`,
`edit`, `apply` and `replace` to fetch and update subresources for all resources that
support them. In Kubernetes version 1.36, only the `status`, `scale`
and `resize` subresources are supported.
  * For `kubectl edit`, the `scale` subresource is not supported. If you use  `--subresource` with
    `kubectl edit` and specify `scale` as the subresource, the command will error out.
* The API contract against a subresource is identical to a full resource. While updating the
`status` subresource to a new value, keep in mind that the subresource could be potentially
reconciled by a controller to a different value.


## Best Practices

### `kubectl run`

For `kubectl run` to satisfy infrastructure as code:

* Tag the image with a version-specific tag and don't move that tag to a new version. For example, use `:v1234`, `v1.2.3`, `r03062016-1-4`, rather than `:latest` (For more information, see [Kubernetes Configuration Good Practices](/blog/2025/11/25/configuration-good-practices/)).
* Check in the script for an image that is heavily parameterized.
* Switch to configuration files checked into source control for features that are needed, but not expressible via `kubectl run` flags.

You can use the `--dry-run=client` flag to preview the object that would be sent to your cluster, without really submitting it.

### `kubectl proxy`

<div class="alert alert-caution" role="note"><h4 class="alert-heading">Caution:</h4><p>Browsing untrusted pod or service endpoints through <code>kubectl proxy</code> is dangerous,
as the served content has implicit access to the Kubernetes API using the proxy's
credentials. Use caution and avoid accessing untrusted endpoints while using
privileged credentials.</p>
<p>To reduce risk:</p>
<ul>
<li>Avoid browsing to untrusted pods or services through <code>kubectl proxy</code>.</li>
<li>Use <code>--reject-methods='POST,PUT,PATCH,DELETE'</code> to restrict the proxy to
read-only operations when you only need to view resources.</li>
<li>Use <code>--reject-paths</code> to limit which API paths the proxy exposes.</li>
<li>Do not run <code>kubectl proxy</code> with cluster-admin credentials unless necessary.</li>
</ul>
</div>


### `kubectl apply`

* You can use `kubectl apply` to create or update resources. For more information about using kubectl apply to update resources, see [Kubectl Book](https://kubectl.docs.kubernetes.io).