Break up examples

hvac · jeffwecan · Jul 14, 2018 · Jul 14, 2018 · Jul 14, 2018 · Jul 14, 2018
commit 63dbf9b8a34e3a2507a2a6459e5ff2840422a75c
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -10,3 +10,9 @@ the latest `vault` binary is available in your `PATH`.
 1. [Install Vault](https://vaultproject.io/docs/install/index.html) or execute `VAULT_BRANCH=release scripts/install-vault-release.sh`
 2. [Install Tox](http://tox.readthedocs.org/en/latest/install.html)
 3. Run tests: `make test`
+
+## Documentation
+
+### Examples
+
+Example code or general guides for methods in this module can be added under [docs/examples](docs/examples).
diff --git a/docs/examples/approle_auth_method.rst b/docs/examples/approle_auth_method.rst
@@ -0,0 +1,9 @@
+Approle Auth Method
+===================
+
+Authentication
+--------------
+
+.. code:: python
+
+    client.auth_approle('MY_ROLE_ID', 'MY_SECRET_ID')
diff --git a/docs/examples/audit.rst b/docs/examples/audit.rst
diff --git a/docs/examples/aws.rst b/docs/examples/aws.rst
@@ -1,9 +1,23 @@
 AWS Authentication Backend
---------------------------
+==========================
 
-To be filled in.
+Authentication
+--------------
+
+IAM authentication method:
+
+.. code:: python
+
+    client.auth_aws_iam('MY_AWS_ACCESS_KEY_ID', 'MY_AWS_SECRET_ACCESS_KEY')
+    client.auth_aws_iam('MY_AWS_ACCESS_KEY_ID', 'MY_AWS_SECRET_ACCESS_KEY', 'MY_AWS_SESSION_TOKEN')
+    client.auth_aws_iam('MY_AWS_ACCESS_KEY_ID', 'MY_AWS_SECRET_ACCESS_KEY', role='MY_ROLE')
+
+    import boto3
+    session = boto3.Session()
+    credentials = session.get_credentials()
+    client.auth_aws_iam(credentials.access_key, credentials.secret_key, credentials.token)
 
 AWS Secret Backend
-------------------
+==================
 
 To be filled in.
diff --git a/docs/examples/examples.rst b/docs/examples/examples.rst
@@ -4,61 +4,27 @@ Examples
 .. toctree::
    :maxdepth: 4
 
-   audit
+   system_backend
+   token_auth_method
    aws
-   sys
+   gcp
+   kubernetes_auth_method
+   approle_auth_method
+   ldap_auth_method
 
 
 Authenticate to different auth backends
 ---------------------------------------
 
 .. code:: python
 
-    # Token
-    client.token = 'MY_TOKEN'
-    assert client.is_authenticated() # => True
 
     # App ID
     client.auth_app_id('MY_APP_ID', 'MY_USER_ID')
 
-    # App Role
-    client.auth_approle('MY_ROLE_ID', 'MY_SECRET_ID')
-
-    # AWS (IAM)
-    client.auth_aws_iam('MY_AWS_ACCESS_KEY_ID', 'MY_AWS_SECRET_ACCESS_KEY')
-    client.auth_aws_iam('MY_AWS_ACCESS_KEY_ID', 'MY_AWS_SECRET_ACCESS_KEY', 'MY_AWS_SESSION_TOKEN')
-    client.auth_aws_iam('MY_AWS_ACCESS_KEY_ID', 'MY_AWS_SECRET_ACCESS_KEY', role='MY_ROLE')
-
-    import boto3
-    session = boto3.Session()
-    credentials = session.get_credentials()
-    client.auth_aws_iam(credentials.access_key, credentials.secret_key, credentials.token)
-
     # GitHub
     client.auth_github('MY_GITHUB_TOKEN')
 
-    # GCP (from GCE instance)
-    import requests
-
-    VAULT_ADDR="https://vault.example.com:8200"
-    ROLE="example"
-    AUDIENCE_URL =  VAULT_ADDR + "/vault/" + ROLE
-    METADATA_HEADERS = {'Metadata-Flavor': 'Google'}
-    FORMAT = 'full'
-
-    url = 'http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience={}&format={}'.format(AUDIENCE_URL, FORMAT)
-    r = requests.get(url, headers=METADATA_HEADERS)
-    client.auth_gcp(ROLE, r.text)
-
-    # Kubernetes (from k8s pod)
-    f = open('/var/run/secrets/kubernetes.io/serviceaccount/token')
-    jwt = f.read()
-    client.auth_kubernetes("example", jwt)
-
-    # LDAP, Username & Password
-    client.auth_ldap('MY_USERNAME', 'MY_PASSWORD')
-    client.auth_userpass('MY_USERNAME', 'MY_PASSWORD')
-
     # TLS
     client = Client(cert=('path/to/cert.pem', 'path/to/key.pem'))
     client.auth_tls()
@@ -81,94 +47,3 @@ Authenticate to different auth backends
 
     # Logout
     client.logout()
-
-Manage tokens
--------------
-
-.. code:: python
-
-    token = client.create_token(policies=['root'], lease='1h')
-
-    current_token = client.lookup_token()
-    some_other_token = client.lookup_token('xxx')
-
-    client.revoke_token('xxx')
-    client.revoke_token('yyy', orphan=True)
-
-    client.revoke_token_prefix('zzz')
-
-    client.renew_token('aaa')
-
-Managing tokens using accessors
--------------------------------
-
-.. code:: python
-
-    token = client.create_token(policies=['root'], lease='1h')
-    token_accessor = token['auth']['accessor']
-
-    same_token = client.lookup_token(token_accessor, accessor=True)
-    client.revoke_token(token_accessor, accessor=True)
-
-Wrapping/unwrapping a token
----------------------------
-
-.. code:: python
-
-    wrap = client.create_token(policies=['root'], lease='1h', wrap_ttl='1m')
-    result = self.client.unwrap(wrap['wrap_info']['token'])
-
-Manipulate auth backends
-------------------------
-
-.. code:: python
-
-    backends = client.list_auth_backends()
-
-    client.enable_auth_backend('userpass', mount_point='customuserpass')
-    client.disable_auth_backend('github')
-
-Manipulate secret backends
---------------------------
-
-.. code:: python
-
-    backends = client.list_secret_backends()
-
-    client.enable_secret_backend('aws', mount_point='aws-us-east-1')
-    client.disable_secret_backend('mysql')
-
-    client.tune_secret_backend('generic', mount_point='test', default_lease_ttl='3600s', max_lease_ttl='8600s')
-    client.get_secret_backend_tuning('generic', mount_point='test')
-
-    client.remount_secret_backend('aws-us-east-1', 'aws-east')
-
-Manipulate policies
--------------------
-
-.. code:: python
-
-    policies = client.list_policies() # => ['root']
-
-    policy = """
-    path "sys" {
-      policy = "deny"
-    }
-
-    path "secret" {
-      policy = "write"
-    }
-
-    path "secret/foo" {
-      policy = "read"
-    }
-    """
-
-    client.set_policy('myapp', policy)
-
-    client.delete_policy('oldthing')
-
-    policy = client.get_policy('mypolicy')
-
-    # Requires pyhcl to automatically parse HCL into a Python dictionary
-    policy = client.get_policy('mypolicy', parse=True)
diff --git a/docs/examples/gcp.rst b/docs/examples/gcp.rst
@@ -0,0 +1,25 @@
+GCP Auth Backend
+================
+
+Authentication
+--------------
+
+.. code:: python
+
+    # GCP (from GCE instance)
+    import requests
+
+    VAULT_ADDR="https://vault.example.com:8200"
+    ROLE="example"
+    AUDIENCE_URL =  VAULT_ADDR + "/vault/" + ROLE
+    METADATA_HEADERS = {'Metadata-Flavor': 'Google'}
+    FORMAT = 'full'
+
+    url = 'http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience={}&format={}'.format(AUDIENCE_URL, FORMAT)
+    r = requests.get(url, headers=METADATA_HEADERS)
+    client.auth_gcp(ROLE, r.text)
+
+GCP Secret Backend
+==================
+
+To be filled in.
diff --git a/docs/examples/kubernetes_auth_method.rst b/docs/examples/kubernetes_auth_method.rst
@@ -0,0 +1,12 @@
+Kubernetes Auth Backend
+=======================
+
+Authentication
+--------------
+
+.. code:: python
+
+    # Kubernetes (from k8s pod)
+    f = open('/var/run/secrets/kubernetes.io/serviceaccount/token')
+    jwt = f.read()
+    client.auth_kubernetes("example", jwt)
diff --git a/docs/examples/ldap_auth_method.rst b/docs/examples/ldap_auth_method.rst
@@ -0,0 +1,11 @@
+LDAP Auth Backend
+=================
+
+Authentication
+--------------
+
+.. code:: python
+
+    # LDAP, Username & Password
+    client.auth_ldap('MY_USERNAME', 'MY_PASSWORD')
+    client.auth_userpass('MY_USERNAME', 'MY_PASSWORD')
diff --git a/docs/examples/sys.rst b/docs/examples/sys.rst