[user-guide] Add object expiration section

Added a section in object storage section on how to expire
objects via the swift cli.

Change-Id: I9d69df509ecff4647c125eec567293a37bd27b68
Closes-Bug: 1654081

doc/user-guide/source/cli-swift-set-object-expiration.rst

@@ -0,0 +1,48 @@
+=================
+Object expiration
+=================
+
+You can schedule Object Storage (swift) objects to expire by setting the
+``X-Delete-At`` or ``X-Delete-After`` header. Once the object is deleted,
+swift will no longer serve the object and it will be deleted from the cluster
+shortly thereafter.
+
+*  Set an object to expire at an absolute time (in Unix time). You
+   can get the current Unix time by running ``date +'%s'``.
+
+   .. code-block:: console
+
+      $ swift post CONTAINER OBJECT_FILENAME -H "X-Delete-At:UNIX_TIME"
+
+   Verify the ``X-Delete-At`` header has posted to the object:
+
+   .. code-block:: console
+
+      $ swift stat CONTAINER OBJECT_FILENAME
+
+*  Set an object to expire after a relative amount of time (in seconds):
+
+   .. code-block:: console
+
+      $ swift post CONTAINER OBJECT_FILENAME -H "X-Delete-After:SECONDS"
+
+   The ``X-Delete-After`` header will be converted to ``X-Delete-At``.
+   Verify the ``X-Delete-At`` header has posted to the object:
+
+   .. code-block:: console
+
+      $ swift stat CONTAINER OBJECT_FILENAME
+
+   If you no longer want to expire the object, you can remove the
+   ``X-Delete-At`` header:
+
+   .. code-block:: console
+
+      $ swift post CONTAINER OBJECT_FILENAME -H "X-Remove-Delete-At:"
+
+.. note::
+
+   In order for object expiration to work properly, the
+   ``swift-object-expirer`` daemon will need access to all backend
+   servers in the cluster. The daemon does not need access to the
+   proxy-server or public network.

doc/user-guide/source/managing-openstack-object-storage-with-swift-cli.rst

@@ -21,6 +21,7 @@ concurrency of 10.
    cli-swift-manage-objects.rst
    cli-swift-env-vars.rst
    cli-swift-set-object-versions.rst
+   cli-swift-set-object-expiration.rst
    cli-swift-serialized-response-formats.rst
    cli-swift-large-lists.rst
    cli-swift-pseudo-hierarchical-folders-directories.rst