Skip to content

Commit 0081145

Browse files
jeffwecanjeffwecan
authored
Merge pull request #222 from ianunruh/docs
🐣 initial docs subdir 🐣
2 parents 93e8cae + 4101a77 commit 0081145

23 files changed

+1847
-551
lines changed

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,6 @@
1212
*~
1313

1414
/hvac/version
15+
16+
# sphinx build folder
17+
docs/_build/

‎CHANGELOG.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,15 @@
11
# Changelog
22

3+
## 0.6.2 (UNRELEASED)
4+
5+
IMPROVEMENTS:
6+
7+
* sphinx documentation and [readthedocs.io project](https://hvac.readthedocs.io/en/latest/) added. [GH-222]
8+
* README.md included in setuptools metadata. [GH-222]
9+
* All `tune_secret_backend()` parameters now accepted. [GH-215]
10+
11+
Thanks to @bbayszczak for their lovely contributions.
12+
313
## 0.6.1 (July 5th, 2018)
414

515
IMPROVEMENTS:

‎CONTRIBUTING.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Contributing
2+
3+
Feel free to open pull requests with additional features or improvements!
4+
5+
## Testing
6+
7+
Integration tests will automatically start a Vault server in the background. Just make sure
8+
the latest `vault` binary is available in your `PATH`.
9+
10+
1. [Install Vault](https://vaultproject.io/docs/install/index.html) or execute `VAULT_BRANCH=release scripts/install-vault-release.sh`
11+
2. [Install Tox](http://tox.readthedocs.org/en/latest/install.html)
12+
3. Run tests: `make test`
13+
14+
## Documentation
15+
16+
### Examples
17+
18+
Example code or general guides for methods in this module can be added under [docs/examples](docs/examples).

‎README.md

Lines changed: 4 additions & 215 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
# HVAC
1+
# hvac
22

33
[HashiCorp](https://hashicorp.com/) [Vault](https://www.vaultproject.io) API client for Python 2/3
44

5-
[![Travis CI](https://travis-ci.org/ianunruh/hvac.svg?branch=master)](https://travis-ci.org/ianunruh/hvac) [![Latest Version](https://img.shields.io/pypi/v/hvac.svg)](https://pypi.python.org/pypi/hvac/)
5+
[![Travis CI](https://travis-ci.org/ianunruh/hvac.svg?branch=master)](https://travis-ci.org/ianunruh/hvac) [![Latest Version](https://img.shields.io/pypi/v/hvac.svg)](https://pypi.python.org/pypi/hvac/) [![Documentation Status](https://readthedocs.org/projects/hvac/badge/)](https://hvac.readthedocs.io/en/latest/?badge=latest)
66

77
Tested against Vault v0.1.2 and HEAD. Requires v0.1.2 or later.
88

@@ -35,11 +35,8 @@ client = hvac.Client(url='http://localhost:8200', token=os.environ['VAULT_TOKEN'
3535
client = hvac.Client(url='https://localhost:8200')
3636

3737
# Using TLS with client-side certificate authentication
38-
client = hvac.Client(url='https://localhost:8200',
39-
cert=('path/to/cert.pem', 'path/to/key.pem'))
38+
client = hvac.Client(url='https://localhost:8200', cert=('path/to/cert.pem', 'path/to/key.pem'))
4039

41-
# Skipping TLS verification entirely (should only be used for local development; unsafe for production clusters)
42-
client = hvac.Client(url='https://localhost:8200', verify=False)
4340
```
4441

4542
### Read and write to secret backends
@@ -52,218 +49,10 @@ print(client.read('secret/foo'))
5249
client.delete('secret/foo')
5350
```
5451

55-
### Authenticate to different auth backends
52+
### Authenticate using token auth backend
5653

5754
```python
5855
# Token
5956
client.token = 'MY_TOKEN'
6057
assert client.is_authenticated() # => True
61-
62-
# App ID
63-
client.auth_app_id('MY_APP_ID', 'MY_USER_ID')
64-
65-
# App Role
66-
client.auth_approle('MY_ROLE_ID', 'MY_SECRET_ID')
67-
68-
# AWS (IAM)
69-
client.auth_aws_iam('MY_AWS_ACCESS_KEY_ID', 'MY_AWS_SECRET_ACCESS_KEY')
70-
client.auth_aws_iam('MY_AWS_ACCESS_KEY_ID', 'MY_AWS_SECRET_ACCESS_KEY', 'MY_AWS_SESSION_TOKEN')
71-
client.auth_aws_iam('MY_AWS_ACCESS_KEY_ID', 'MY_AWS_SECRET_ACCESS_KEY', role='MY_ROLE')
72-
73-
import boto3
74-
session = boto3.Session()
75-
credentials = session.get_credentials()
76-
client.auth_aws_iam(credentials.access_key, credentials.secret_key, credentials.token)
77-
78-
# GitHub
79-
client.auth_github('MY_GITHUB_TOKEN')
80-
81-
# GCP (from GCE instance)
82-
import requests
83-
84-
VAULT_ADDR="https://vault.example.com:8200"
85-
ROLE="example"
86-
AUDIENCE_URL = VAULT_ADDR + "/vault/" + ROLE
87-
METADATA_HEADERS = {'Metadata-Flavor': 'Google'}
88-
FORMAT = 'full'
89-
90-
url = 'http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience={}&format={}'.format(AUDIENCE_URL, FORMAT)
91-
r = requests.get(url, headers=METADATA_HEADERS)
92-
client.auth_gcp(ROLE, r.text)
93-
94-
# Kubernetes (from k8s pod)
95-
f = open('/var/run/secrets/kubernetes.io/serviceaccount/token')
96-
jwt = f.read()
97-
client.auth_kubernetes("example", jwt)
98-
99-
# LDAP, Username & Password
100-
client.auth_ldap('MY_USERNAME', 'MY_PASSWORD')
101-
client.auth_userpass('MY_USERNAME', 'MY_PASSWORD')
102-
103-
# TLS
104-
client = Client(cert=('path/to/cert.pem', 'path/to/key.pem'))
105-
client.auth_tls()
106-
107-
# Non-default mount point (available on all auth types)
108-
client.auth_userpass('MY_USERNAME', 'MY_PASSWORD', mount_point='CUSTOM_MOUNT_POINT')
109-
110-
# Authenticating without changing to new token (available on all auth types)
111-
result = client.auth_github('MY_GITHUB_TOKEN', use_token=False)
112-
print(result['auth']['client_token']) # => u'NEW_TOKEN'
113-
114-
# Custom or unsupported auth type
115-
params = {
116-
'username': 'MY_USERNAME',
117-
'password': 'MY_PASSWORD',
118-
'custom_param': 'MY_CUSTOM_PARAM',
119-
}
120-
121-
result = client.auth('/v1/auth/CUSTOM_AUTH/login', json=params)
122-
123-
# Logout
124-
client.logout()
12558
```
126-
127-
### Manage tokens
128-
129-
```python
130-
token = client.create_token(policies=['root'], lease='1h')
131-
132-
current_token = client.lookup_token()
133-
some_other_token = client.lookup_token('xxx')
134-
135-
client.revoke_token('xxx')
136-
client.revoke_token('yyy', orphan=True)
137-
138-
client.revoke_token_prefix('zzz')
139-
140-
client.renew_token('aaa')
141-
```
142-
143-
### Managing tokens using accessors
144-
145-
```python
146-
token = client.create_token(policies=['root'], lease='1h')
147-
token_accessor = token['auth']['accessor']
148-
149-
same_token = client.lookup_token(token_accessor, accessor=True)
150-
client.revoke_token(token_accessor, accessor=True)
151-
```
152-
153-
### Wrapping/unwrapping a token
154-
155-
```python
156-
wrap = client.create_token(policies=['root'], lease='1h', wrap_ttl='1m')
157-
result = self.client.unwrap(wrap['wrap_info']['token'])
158-
```
159-
160-
### Manipulate auth backends
161-
162-
```python
163-
backends = client.list_auth_backends()
164-
165-
client.enable_auth_backend('userpass', mount_point='customuserpass')
166-
client.disable_auth_backend('github')
167-
```
168-
169-
### Manipulate secret backends
170-
171-
```python
172-
backends = client.list_secret_backends()
173-
174-
client.enable_secret_backend('aws', mount_point='aws-us-east-1')
175-
client.disable_secret_backend('mysql')
176-
177-
client.tune_secret_backend('generic', mount_point='test', default_lease_ttl='3600s', max_lease_ttl='8600s')
178-
client.get_secret_backend_tuning('generic', mount_point='test')
179-
180-
client.remount_secret_backend('aws-us-east-1', 'aws-east')
181-
```
182-
183-
### Manipulate policies
184-
185-
```python
186-
policies = client.list_policies() # => ['root']
187-
188-
policy = """
189-
path "sys" {
190-
policy = "deny"
191-
}
192-
193-
path "secret" {
194-
policy = "write"
195-
}
196-
197-
path "secret/foo" {
198-
policy = "read"
199-
}
200-
"""
201-
202-
client.set_policy('myapp', policy)
203-
204-
client.delete_policy('oldthing')
205-
206-
policy = client.get_policy('mypolicy')
207-
208-
# Requires pyhcl to automatically parse HCL into a Python dictionary
209-
policy = client.get_policy('mypolicy', parse=True)
210-
```
211-
212-
### Manipulate audit backends
213-
214-
```python
215-
backends = client.list_audit_backends()
216-
217-
options = {
218-
'path': '/tmp/vault.log',
219-
'log_raw': True,
220-
}
221-
222-
client.enable_audit_backend('file', options=options, name='somefile')
223-
client.disable_audit_backend('oldfile')
224-
```
225-
226-
### Initialize and seal/unseal
227-
228-
```python
229-
print(client.is_initialized()) # => False
230-
231-
shares = 5
232-
threshold = 3
233-
234-
result = client.initialize(shares, threshold)
235-
236-
root_token = result['root_token']
237-
keys = result['keys']
238-
239-
print(client.is_initialized()) # => True
240-
241-
print(client.is_sealed()) # => True
242-
243-
# unseal with individual keys
244-
client.unseal(keys[0])
245-
client.unseal(keys[1])
246-
client.unseal(keys[2])
247-
248-
# unseal with multiple keys until threshold met
249-
client.unseal_multi(keys)
250-
251-
print(client.is_sealed()) # => False
252-
253-
client.seal()
254-
255-
print(client.is_sealed()) # => True
256-
```
257-
258-
## Testing
259-
260-
Integration tests will automatically start a Vault server in the background. Just make sure
261-
the latest `vault` binary is available in your `PATH`.
262-
263-
1. [Install Vault](https://vaultproject.io/docs/install/index.html) or execute `VAULT_BRANCH=release scripts/install-vault-release.sh`
264-
2. [Install Tox](http://tox.readthedocs.org/en/latest/install.html)
265-
3. Run tests: `make test`
266-
267-
## Contributing
268-
269-
Feel free to open pull requests with additional features or improvements!

‎docs/Makefile

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS = -E -a
6+
SPHINXBUILD = sphinx-build
7+
SPHINXPROJ = hvac
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/changelog.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.. mdinclude:: ../CHANGELOG.md

‎docs/conf.py

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# -*- coding: utf-8 -*-
2+
# Configuration file for the Sphinx documentation builder.
3+
4+
5+
# -- Path setup --------------------------------------------------------------
6+
# Set up import path to allow the autodoc extension to find the local module code.
7+
import os
8+
import sys
9+
sys.path.insert(0, os.path.abspath('..'))
10+
11+
12+
# -- Project information -----------------------------------------------------
13+
14+
project = u'hvac'
15+
copyright = u'2018, Ian Unruh, Jeffrey Hogan'
16+
author = u'Ian Unruh, Jeffrey Hogan'
17+
18+
# The short X.Y version
19+
version = u'0.6.1'
20+
# The full version, including alpha/beta/rc tags
21+
release = u'0.6.1'
22+
23+
24+
# -- General configuration ---------------------------------------------------
25+
26+
extensions = [
27+
'sphinx.ext.autodoc',
28+
'sphinx.ext.doctest',
29+
'sphinx.ext.coverage',
30+
'sphinx.ext.viewcode',
31+
'sphinx.ext.githubpages',
32+
'm2r',
33+
]
34+
35+
# Add any paths that contain templates here, relative to this directory.
36+
templates_path = ['_templates']
37+
38+
source_suffix = ['.rst', '.md']
39+
40+
# The master toctree document.
41+
master_doc = 'index'
42+
43+
language = None
44+
exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store']
45+
pygments_style = 'sphinx'
46+
47+
48+
# -- Options for HTML output -------------------------------------------------
49+
50+
html_theme = 'sphinx_rtd_theme'
51+
html_static_path = ['_static']
52+
53+
54+
# -- Options for HTMLHelp output ---------------------------------------------
55+
56+
# Output file base name for HTML help builder.
57+
htmlhelp_basename = 'hvacdoc'
58+
59+
# -- Options for Epub output -------------------------------------------------
60+
61+
# Bibliographic Dublin Core info.
62+
epub_title = project
63+
epub_author = author
64+
epub_publisher = author
65+
epub_copyright = copyright
66+
67+
# A list of files that should not be packed into the epub file.
68+
epub_exclude_files = ['search.html']
69+
70+
# -- Extension configuration -------------------------------------------------

‎docs/contributing.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.. mdinclude:: ../CONTRIBUTING.md

‎docs/examples/approle_auth_method.rst

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
Approle Auth Method
2+
===================
3+
4+
Authentication
5+
--------------
6+
7+
.. code:: python
8+
9+
client.auth_approle('MY_ROLE_ID', 'MY_SECRET_ID')

0 commit comments

Comments
 (0)