README

vaultlib

Build Status Coverage Status GoDoc Go Report Card

Lightweight, simple Go library for Vault secret reading (http API).

Connect to Vault through app role or token.

Reads kv secret values

Features

  • Connect to Vault through app role
  • Read Vault secret, kv type (v1 or v2 "versioned")
  • Automatically renew token
  • Execute any HTTP request on Vault (RawRequest)

Config

Configuration can be done through env variables or programmatically through the Config object The following env variables are supported:

VAULT_ADDR            Vault server URL (default http://localhost:8200)
VAULT_CAPATH          CA path
VAULT_TOKEN           Vault Token
VAULT_ROLEID          Vault app role id
VAULT_SECRETID        Vault app role secret id
VAULT_CLIENT_TIMEOUT  Client timeout
VAULT_SKIP_VERIFY     Do not check SSL

If not set, vaultlib will fallback to safe default values.

Getting Started

For a simple, working example, check the sample folder.

package main

import (
    "fmt"
    "log"
    "os"

    vault "github.com/mch1307/vaultlib"
)

func main() {
    // Config can be set through ENV before invoking NewConfig
    os.Setenv("VAULT_ADDR", "http://localhost:8200")

    // Create a new config. Reads env variables, fallback to default value if needed
    vcConf := vault.NewConfig()

    // Config can also be done programmtically
    vcConf.Address = "http://localhost:8200"

    // set app role credentials (ie after reading from docker secret)
    // vcConf.AppRoleCredentials.RoleID = "myRoleID"
    // vcConf.AppRoleCredentials.SecretID = "mySecretID"

    // Create new client
    vaultCli, err := vault.NewClient(vcConf)
    if err != nil {
        log.Fatal(err)
    }

    // Get the Vault secret data
    kv, err := vaultCli.GetSecret("my_kv/my_org/my_secret")
    if err != nil {
        fmt.Println(err)
    }
    for k, v := range kv {
        fmt.Printf("secret %v: %v\n", k, v)
    }
}

Documentation

Overview

Package vaultlib is a lightweight Go library for reading Vault KV secrets. Interacts with Vault server using HTTP API only.

First create a new *config object using NewConfig().

Then create you Vault client using NewClient(*config).

Example
// Create a new config. Reads env variables, fallback to default value if needed
vcConf := NewConfig()

// Add the Vault approle secretid after having read it from docker secret
// vcConf.AppRoleCredentials.SecretID

// Create new client
vaultCli, err := NewClient(vcConf)
if err != nil {
	log.Fatal(err)
}

// Get the Vault KV secret from kv_v1/path/my-secret
kvV1, err := vaultCli.GetSecret("kv_v1/path/my-secret")
if err != nil {
	fmt.Println(err)
}
for k, v := range kvV1.KV {
	fmt.Printf("Secret %v: %v\n", k, v)
}
// Get the Vault KVv2 secret kv_v2/path/my-secret
kvV2, err := vaultCli.GetSecret("kv_v2/path/my-secret")
if err != nil {
	fmt.Println(err)
}
for k, v := range kvV2.KV {
	fmt.Printf("Secret %v: %v\n", k, v)
}
jsonSecret, err := vaultCli.GetSecret("kv_v2/path/json-secret")
if err != nil {
	fmt.Println(err)
}
fmt.Println(fmt.Sprintf("%v", jsonSecret.JSONSecret))
Output:

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AppRoleCredentials

type AppRoleCredentials struct {
	RoleID   string `json:"role_id"`
	SecretID string `json:"secret_id"`
}

AppRoleCredentials holds the app role secret and role ids

type Client

type Client struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

Client holds the vault client

func NewClient

func NewClient(c *Config) (*Client, error)

NewClient returns a new client based on the provided config

Example
myConfig := NewConfig()
myVaultClient, err := NewClient(myConfig)
if err != nil {
	fmt.Println(err)
}
fmt.Println(myVaultClient.address)
Output:

func (*Client) GetSecret

func (c *Client) GetSecret(path string) (secret Secret, err error)

GetSecret returns the Vault secret object

KV: map[string]string if the secret is a KV

JSONSecret: json.RawMessage if the secret is a json

func (*Client) GetStatus

func (c *Client) GetStatus() string

GetStatus return the last action status/log

func (*Client) GetTokenInfo

func (c *Client) GetTokenInfo() *VaultTokenInfo

GetTokenInfo returns the current token information

func (*Client) IsAuthenticated

func (c *Client) IsAuthenticated() bool

IsAuthenticated returns bool if last call to vault was ok

Example
myConfig := NewConfig()
myVaultClient, err := NewClient(myConfig)
if err != nil {
	fmt.Println(err)
}
if myVaultClient.IsAuthenticated() {
	fmt.Println("myVaultClient's connection is ok")
}
Output:

func (*Client) RawRequest

func (c *Client) RawRequest(method, path string, payload interface{}) (result json.RawMessage, err error)

RawRequest create and execute http request against Vault HTTP API for client. Use the client's token for authentication.

Specify http method, Vault path (ie /v1/auth/token/lookup) and optional json payload. Return the Vault JSON response .

type Config

type Config struct {
	Address            string
	MaxRetries         int
	Timeout            time.Duration
	CAPath             string
	InsecureSSL        bool
	AppRoleCredentials *AppRoleCredentials
	Token              string
}

Config holds the vault client config

func NewConfig

func NewConfig() *Config

NewConfig returns a new configuration based on env vars or default value.

Reads ENV:

VAULT_ADDR            Vault server URL (default http://localhost:8200)
VAULT_CAPATH          CA path
VAULT_TOKEN           Vault Token
VAULT_ROLEID          Vault app role id
VAULT_SECRETID        Vault app role secret id
VAULT_CLIENT_TIMEOUT  Client timeout
VAULT_SKIP_VERIFY     Do not check SSL

Modify the returned config object to make proper configuration.

Example
myConfig := NewConfig()
myConfig.Address = "http://localhost:8200"
Output:

type Secret

type Secret struct {
	KV         map[string]string
	JSONSecret json.RawMessage
}

Secret holds the secret.

KV contains data in case of KV secret.

JSONSecret contains data in case of JSON raw secret.

type VaultTokenInfo

type VaultTokenInfo struct {
	Accessor       string      `json:"accessor"`
	CreationTime   int         `json:"creation_time"`
	CreationTTL    int         `json:"creation_ttl"`
	DisplayName    string      `json:"display_name"`
	EntityID       string      `json:"entity_id"`
	ExpireTime     interface{} `json:"expire_time"`
	ExplicitMaxTTL int         `json:"explicit_max_ttl"`
	ID             string      `json:"id"`
	IssueTime      time.Time   `json:"issue_time"`
	Meta           interface{} `json:"meta"`
	NumUses        int         `json:"num_uses"`
	Orphan         bool        `json:"orphan"`
	Path           string      `json:"path"`
	Policies       []string    `json:"policies"`
	Renewable      bool        `json:"renewable"`
	TTL            int         `json:"ttl"`
	Type           string      `json:"type"`
}

VaultTokenInfo holds the Vault token information

Directories

Path Synopsis