README
¶
caddy-kubernetes-storage
Kubernetes storage for caddy's TLS data
Running within a kubernetes pod
All that is needed is adding the storage "kubernetes" directive to the tls block in your caddy file
Running outside a kubernetes pod, or with a custom config
Add the storage "kubernetes" directive to the tls block in your caddy file, in addition, define the following environment variables:
CADDY_K8S_CONF_PATH: The path to a JSON kubernetes config file. The JSON format corresponding to the kubernetes config struct found hereCADDY_K8S_NAMESPACE: The namespace to use for creating and retrieving secrets.
Storage method
The plugin will create kubernetes secrets to store TLS certificates, user data as well as email data. The naming scheme for the secrets looks as follows:
- Domain specific data:
caddy-domain-[domain name] - User specific data:
caddy-user-[base32 hex-encoded email] - Global data:
caddy-global
Installation
You should vendor the k8s.io/kubernetes repository in your own code, and use the correct release-1.x branch that corresponds with the version of kubernetes that you use.
This is because the master branch of k8s.io/kubernetes is meant for the in development version of kubernetes, which your cluster is probably not running, and often does not compile.
This code is tested with the latest release branch of kubernetes, currently that is release-1.3
Once you have the correct version of kubernetes vendored, you can just run go get github.com/PalmStoneGames/caddy-kubernetes-storage/...
License
This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
Documentation
¶
Index ¶
- type Storage
- func (k *Storage) DeleteSite(domain string) error
- func (k *Storage) LoadSite(domain string) (*caddytls.SiteData, error)
- func (k *Storage) LoadUser(email string) (*caddytls.UserData, error)
- func (k *Storage) LockRegister(domain string) (bool, error)
- func (k *Storage) MostRecentUserEmail() string
- func (k *Storage) SiteExists(domain string) (bool, error)
- func (k *Storage) StoreSite(domain string, data *caddytls.SiteData) error
- func (k *Storage) StoreUser(email string, data *caddytls.UserData) error
- func (k *Storage) UnlockRegister(domain string) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Storage ¶
type Storage struct {
// contains filtered or unexported fields
}
Storage represents a caddy kubernetes storage. Use one of NewStorageAuto, NewStorageInCluster or NewStorageWithConfig to initialize.
func NewStorageAuto ¶
NewStorageAuto attempts to determine whether to call NewStorageWithConfig or NewStorageInCluster. It will call NewStorageWithConfig if the following env vars are declared: CADDY_K8S_CONF_PATH, CADDY_K8S_NAMESPACE Otherwise, it will call NewStorageInCluster.
func NewStorageInCluster ¶
NewStorageInCluster will initialize a new Storage. Login credentials will be taken from the kubernetes pod. If not in a cluster, use NewStorageWithConfig.
func NewStorageWithConfig ¶
NewStorageWithConfig will initialize a new storage based on the passed config and namespace.
func (*Storage) DeleteSite ¶
DeleteSite deletes the site for the given domain from storage. If the site does not exist, the ErrStorageNotFound error instance is returned.
func (*Storage) LoadSite ¶
LoadSite obtains the site data from storage for the given domain and returns it. If data for the domain does not exist, the ErrStorageNotFound error instance is returned. care has been taken to make this load atomic to prevent race conditions that happen with multiple data loads.
func (*Storage) LoadUser ¶
LoadUser obtains user data from storage for the given email and returns it. If data for the email does not exist, the ErrStorageNotFound error instance is returned. Multi-server implementations should take care to make this operation atomic for all loaded data items.
func (*Storage) LockRegister ¶
LockRegister should be called before the caller attempts to obtain or renew a certificate. This function is used as a mutex/semaphore for making sure something else isn't already attempting obtain/renew. It will return true (without error) if the lock is successfully obtained meaning nothing else is attempting renewal. It will return false (without error) if this domain is already locked by something else attempting renewal. To prevent deadlocks, the lock has a timeout of two minutes. Errors are only returned in exceptional cases.
func (*Storage) MostRecentUserEmail ¶
MostRecentUserEmail provides the most recently used email parameter in StoreUser. The result is an empty string if there are no persisted users in storage.
func (*Storage) SiteExists ¶
SiteExists returns true if this site exists in storage. Site data is considered present when StoreSite has been called successfully (without DeleteSite having been called, of course).
func (*Storage) StoreSite ¶
StoreSite persists the given site data for the given domain in storage. Care has been taken to make this call atomic to prevent half-written data on failure of an internal intermediate storage step. this function should only be invoked after LockRegister and before UnlockRegister of the same domain.
func (*Storage) StoreUser ¶
StoreUser persists the given user data for the given email in storage. Care has been taken to make this operation atomic for all stored data items.
func (*Storage) UnlockRegister ¶
UnlockRegister should be called after the caller has attempted to obtain or renew a certificate, regardless of whether it was successful. This will attempt to unlock the lock obtained in this process by LockRegister. If no lock exists, the implementation will not return an error. Errors are only returned in exceptional cases.
Source Files