Merge pull request #40 from plttn/jack/readme-updates

Update readme to remove ambiguity

README.md

@@ -123,26 +123,31 @@ spec:
 
 </details>
 
-**Note:** Injected secrets are available *only* in the current pod's session.
+To inject secrets, the Pod you're looking to inject into must have a `command` value defined in its [Deployment or Pod spec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#container-v1-core). The 1Password Secrets Injector works by mutating the this value on initilization, and as such a command is needed to be mutated. If the deployments you're using aren't designed to have `command` specified in the deployment, then the 1Password Kubernetes Operator may be a better fit for your use case.
+
+**Note:** Injected secrets are available *only* in the current pod's session. In other words, the secrets will only be accessible for the command listed in the container specification. To access it in any other session, for example using `kubectl exec`, it's necessary to prepend `op run --` to the command.
+
 
 In the example above the `app-example1` container will have injected the `DB_USERNAME` and `DB_PASSWORD` values in the session executed by the command `npm start`.
-If you want to access them in a new session (for example using `kubectl exec`) you should append `op run --` to the command executed in the container's new session.
 
 Another alternative to have the secrets available in all container's sessions is by using the [1Password Kubernetes Operator](https://github.com/1password/onepassword-operator).
 
 ## Setup and Deployment
 
 ### Prerequisites
+
 - [docker installed](https://docs.docker.com/get-docker/)
 - [kubectl installed](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
 
 If you want to use 1Password Connect:
+
 - [Set up a Secrets Automation workflow](https://developer.1password.com/docs/connect/get-started#step-1-set-up-a-secrets-automation-workflow).
 - [Deploy 1Password Connect](https://developer.1password.com/docs/connect/get-started#step-2-deploy-1password-connect-server) in your Kubernetes infrastructure.
 
 Then, follow instructions to [use the Kubernetes Injector](#use-with-1password-connect).
 
 If you want to use 1Password Service Accounts:
+
 - [Create a service account.](https://developer.1password.com//docs/service-accounts/)
 
 Then, follow instructions to [use the Kubernetes Injector with a service account](#use-with-1password-service-accounts).
@@ -166,12 +171,13 @@ kubectl label namespace default secrets-injection=enabled
 ```shell
 make deploy
 ```
-**NOTE:** The injector creates the TLS certificate required for the webhook to work on the fly when deploying the injector (`deployment.yaml`). When the injector is removed from the cluster, it will delete the certificate.
 
+**NOTE:** The injector creates the TLS certificate required for the webhook to work on the fly when deploying the injector ([`deployment.yaml`](/deploy/deployment.yaml)). When the injector is removed from the cluster, it will delete the certificate.
 
 ### Step 4: Annotate your client pod or deployment with `inject` annotation
 
 Annotate your client pod or deployment spec with `operator.1password.io/inject`. It expects a comma separated list of the names of the containers that will be mutated and have secrets injected.
+
 ```yaml
 # client-deployment.yaml
 annotations:
@@ -190,7 +196,8 @@ env:
 
 ### Step 6: Provide 1Password CLI credentials on your pod or deployment
 
-You can provide your pod or deployment with 1Password CLI credentials by [creating Kubernetes Secrets](#step-1-create-a-kubernetes-secret-containing-opconnecttoken) and referring to them in your deployment configuration.
+Provide your Pod or Deployment with 1Password CLI credentials to perform the injection. One possibility to safely provide these credentials is to [create a Kubernetes Secret](#step-1-create-a-kubernetes-secret-containing-opconnecttoken) and refer to it in your deployment configuration.
+
 ```yaml
 # your-app-pod/deployment.yaml
 env:
@@ -208,39 +215,49 @@ env:
 ## Use with 1Password Service Accounts
 
 ### Step 1: Create a Kubernetes secret containing `OP_SERVICE_ACCOUNT_TOKEN`
+
 ```
 kubectl create secret generic op-service-account --from-literal=token=YOUR_OP_SERVICE_ACCOUNT_TOKEN
 ```
 
-### Step 2: Add the label `secrets-injection=enabled` label to the namespace:
+### Step 2: Add the label `secrets-injection=enabled` label to the namespace
+
 ```
 kubectl label namespace default secrets-injection=enabled
 ```
 
 ### Step 3: Deploy injector
+
 ```
 make deploy
 ```
+
 **NOTE:** The injector creates the TLS certificate required for the webhook to work on the fly when deploying the injector (`deployment.yaml`). When the injector is removed from the cluster, it will delete the certificate.
 
 ### Step 4: Annotate your client pod or deployment with `inject` annotation
+
 Annotate your client pod or deployment spec with `operator.1password.io/inject`. It expects a comma separated list of the names of the containers that will be mutated and have secrets injected.
+
 ```yaml
 # client-deployment.yaml
 annotations:
   operator.1password.io/inject: "app-example1"
 ```
 
 ### Step 5: Annotate your client pod or deployment with `version` annotation
+
 Annotate your client pod or deployment with the latest version of the 1Password CLI (`2.18.0` or later).
+
 ```yaml
 # client-deployment.yaml
 annotations:
   operator.1password.io/version: "2-beta"
 ```
 
 ### Step 6: Configure the resource's environment
+
 Add an environment variable to the resource with a value referencing your 1Password item. Use the following secret reference syntax: `op://<vault>/<item>[/section]/<field>`.
+
 ```yaml
 # client-deployment.yaml
 env:
@@ -250,7 +267,8 @@ env:
 
 ### Step 7: Provide 1Password CLI credentials on your pod or deployment
 
-You can provide your pod or deployment with 1Password CLI credentials by [creating Kubernetes Secrets](#step-1-create-a-kubernetes-secret-containing-opserviceaccounttoken) and referring to them in your deployment configuration.
+Provide your Pod or Deployment with 1Password CLI credentials to perform the injection. One possibility to safely provide these secrets is to [create a Kubernetes Secret](#step-1-create-a-kubernetes-secret-containing-opserviceaccounttoken) and refer to it in your deployment configuration.
+
 ```yaml
 # client-deployment.yaml
 env:
@@ -266,6 +284,7 @@ env:
 ## Troubleshooting
 
 If you can't inject secrets in your pod, make sure:
+
 - The namespace of your pod has the `secrets-injection=enabled` label
 - The 1Password Secret Injector webhook is running (`secrets-injector` by default).
 - Your container has a `command` field specifying the command to run the app in your container