Merge "Restore Zuul v3 Migration Guide bits on secrets"

doc/source/drivers.rst

@@ -297,6 +297,37 @@ Those looking to write and run jobs with Zuul can refer to Zuul's
 `documentation <https://zuul-ci.org/docs/zuul/reference/config.html>`__
 in order to get started.
 
+.. _using-secrets:
+
+Using Secrets
+-------------
+
+.. sidebar:: Further reading
+
+   See the `Encryption
+   <https://zuul-ci.org/docs/zuul/user/encryption.html>`_ section of the
+   Zuul User Guide for more information on encryption and secrets, and
+   the :ref:`handling-zuul-secrets` section of the Test Environment
+   chapter for OpenDev's secret handling policy.
+
+Zuul makes it convenient to provide secrets which can be used to perform
+tasks with jobs run in post-review pipelines, like authenticating a job
+to a remote service or generating cryptographic signatures
+automatically. These secrets are asymmetrically encrypted for inclusion
+in job definitions using per-project public keys served from a Zuul API,
+and are presented in their decrypted form as Ansible variables the jobs
+can use.
+
+If you want to encrypt a secret, you can use the
+``tools/encrypt_secret.py`` script from project
+``zuul/zuul``. For example, to encrypt file
+``file_with_secret`` for project ``openstack/kolla`` use:
+
+.. code-block:: shell
+
+   $ tools/encrypt_secret.py --infile file_with_secret \
+     --tenant openstack https://zuul.opendev.org openstack/kolla
+
 Retiring a Project
 ==================
 

doc/source/testing.rst

@@ -141,3 +141,25 @@ resources quickly.
 We are also always happy to add resources if they are available, but the
 priority from the project should be to ensure we are using what we do have
 responsibly.
+
+.. _handling-zuul-secrets:
+
+Handling Zuul Secrets
+=====================
+
+Zuul secrets are the expected means of safely incorporating secret data
+(e.g., passwords or cryptographic keys) into job definitions. See the
+:ref:`using-secrets` section of the Project Driver's Guide chapter for
+some basic user guidance on this feature.
+
+Credentials and similar secrets encrypted for the per-project keys Zuul
+uses cannot be decrypted except by Zuul and (by extension) the root
+sysadmins operating the Zuul service and maintaining the job nodes where
+those secrets are utilized. By policy, these sysadmins will not
+deliberately decrypt secrets or access decrypted secrets, aside from
+non-production test vectors used to ensure the feature is working
+correctly. They will not under any circumstances be able to provide
+decrypted copies of your project's secrets on request, and so you cannot
+consider the encrypted copy as a backup but should instead find ways to
+safely maintain (and if necessary share) your own backup copies if
+you're unable to easily revoke/replace them when lost.