217 lines
6.6 KiB
Markdown
217 lines
6.6 KiB
Markdown
|
# triton-go
|
||
|
|
|
||
|
|
`go-triton` is an idiomatic library exposing a client SDK for Go applications using the Joyent Triton API.
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
|
||
|
|
Triton uses [HTTP Signature][4] to sign the Date header in each HTTP request made to the Triton API. Currently, requests can be signed using either a private key file loaded from disk (using an [`authentication.PrivateKeySigner`][5]), or using a key stored with the local SSH Agent (using an [`SSHAgentSigner`][6].
|
||
|
|
|
||
|
|
To construct a Signer, use the `New*` range of methods in the `authentication` package. In the case of `authentication.NewSSHAgentSigner`, the parameters are the fingerprint of the key with which to sign, and the account name (normally stored in the `SDC_ACCOUNT` environment variable). For example:
|
||
|
|
|
||
|
|
```
|
||
|
|
const fingerprint := "a4:c6:f3:75:80:27:e0:03:a9:98:79:ef:c5:0a:06:11"
|
||
|
|
sshKeySigner, err := authentication.NewSSHAgentSigner(fingerprint, "AccountName")
|
||
|
|
if err != nil {
|
||
|
|
log.Fatalf("NewSSHAgentSigner: %s", err)
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
An appropriate key fingerprint can be generated using `ssh-keygen`:
|
||
|
|
|
||
|
|
```
|
||
|
|
ssh-keygen -Emd5 -lf ~/.ssh/id_rsa.pub | cut -d " " -f 2 | sed 's/MD5://'
|
||
|
|
```
|
||
|
|
|
||
|
|
To construct a Client, use the `NewClient` function, passing in the endpoint, account name and constructed signer:
|
||
|
|
|
||
|
|
```go
|
||
|
|
client, err := triton.NewClient("https://us-sw-1.api.joyent.com/", "AccountName", sshKeySigner)
|
||
|
|
if err != nil {
|
||
|
|
log.Fatalf("NewClient: %s", err)
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
Having constructed a `triton.Client`, use the methods available to access functionality by functional grouping. For example, for access to operations on SSH keys, use the `Keys()` method to obtain a client which has access to the `CreateKey`, `ListKeys` and `DeleteKey` operations. For access to operations on Machines, use the `Machines()` method to obtain a client which has access to the `RenameMachine`, `GetMachineMetadata`, `GetMachineTag`, and other operations.
|
||
|
|
|
||
|
|
Operation methods take their formal parameters via a struct named `OperationInput` - for example when creating an SSH key, the `CreateKeyInput` struct is used with the `func CreateKey(*CreateKeyInput) (*Key, error)` method. This allows specification of named parameters:
|
||
|
|
|
||
|
|
```
|
||
|
|
client := state.Client().Keys()
|
||
|
|
|
||
|
|
key, err := client.CreateKey(&CreateKeyInput{
|
||
|
|
Name: "tempKey",
|
||
|
|
Key: "ssh-rsa .....",
|
||
|
|
})
|
||
|
|
if err != nil {
|
||
|
|
panic(err)
|
||
|
|
}
|
||
|
|
|
||
|
|
// Key contains the return value.
|
||
|
|
```
|
||
|
|
|
||
|
|
## Error Handling
|
||
|
|
|
||
|
|
If an error is returned by the HTTP API, the `error` returned from the function will contain an instance of `triton.TritonError` in the chain. Error wrapping is performed using the [errwrap][7] library from HashiCorp.
|
||
|
|
|
||
|
|
## Completeness
|
||
|
|
|
||
|
|
The following list is updated as new functionality is added. The complete list of operations is taken from the [CloudAPI documentation](https://apidocs.joyent.com/cloudapi).
|
||
|
|
|
||
|
|
- Accounts
|
||
|
|
- [x] GetAccount
|
||
|
|
- [x] UpdateAccount
|
||
|
|
- Keys
|
||
|
|
- [x] ListKeys
|
||
|
|
- [x] GetKey
|
||
|
|
- [x] CreateKey
|
||
|
|
- [x] DeleteKey
|
||
|
|
- Users
|
||
|
|
- [ ] ListUsers
|
||
|
|
- [ ] GetUser
|
||
|
|
- [ ] CreateUser
|
||
|
|
- [ ] UpdateUser
|
||
|
|
- [ ] ChangeUserPassword
|
||
|
|
- [ ] DeleteUser
|
||
|
|
- Roles
|
||
|
|
- [x] ListRoles
|
||
|
|
- [x] GetRole
|
||
|
|
- [x] CreateRole
|
||
|
|
- [x] UpdateRole
|
||
|
|
- [x] DeleteRole
|
||
|
|
- Role Tags
|
||
|
|
- [ ] SetRoleTags
|
||
|
|
- Policies
|
||
|
|
- [ ] ListPolicies
|
||
|
|
- [ ] GetPolicy
|
||
|
|
- [ ] CreatePolicy
|
||
|
|
- [ ] UpdatePolicy
|
||
|
|
- [ ] DeletePolicy
|
||
|
|
- User SSH Keys
|
||
|
|
- [x] ListUserKeys
|
||
|
|
- [x] GetUserKey
|
||
|
|
- [x] CreateUserKey
|
||
|
|
- [x] DeleteUserKey
|
||
|
|
- Config
|
||
|
|
- [x] GetConfig
|
||
|
|
- [x] UpdateConfig
|
||
|
|
- Datacenters
|
||
|
|
- [x] ListDatacenters
|
||
|
|
- [x] GetDatacenter
|
||
|
|
- Services
|
||
|
|
- [x] ListServices
|
||
|
|
- Images
|
||
|
|
- [x] ListImages
|
||
|
|
- [x] GetImage
|
||
|
|
- [x] DeleteImage
|
||
|
|
- [x] ExportImage
|
||
|
|
- [x] CreateImageFromMachine
|
||
|
|
- [x] UpdateImage
|
||
|
|
- Packages
|
||
|
|
- [x] ListPackages
|
||
|
|
- [x] GetPackage
|
||
|
|
- Instances
|
||
|
|
- [ ] ListMachines
|
||
|
|
- [x] GetMachine
|
||
|
|
- [x] CreateMachine
|
||
|
|
- [ ] StopMachine
|
||
|
|
- [ ] StartMachine
|
||
|
|
- [ ] RebootMachine
|
||
|
|
- [x] ResizeMachine
|
||
|
|
- [x] RenameMachine
|
||
|
|
- [x] EnableMachineFirewall
|
||
|
|
- [x] DisableMachineFirewall
|
||
|
|
- [ ] CreateMachineSnapshot
|
||
|
|
- [ ] StartMachineFromSnapshot
|
||
|
|
- [ ] ListMachineSnapshots
|
||
|
|
- [ ] GetMachineSnapshot
|
||
|
|
- [ ] DeleteMachineSnapshot
|
||
|
|
- [x] UpdateMachineMetadata
|
||
|
|
- [ ] ListMachineMetadata
|
||
|
|
- [ ] GetMachineMetadata
|
||
|
|
- [ ] DeleteMachineMetadata
|
||
|
|
- [ ] DeleteAllMachineMetadata
|
||
|
|
- [x] AddMachineTags
|
||
|
|
- [x] ReplaceMachineTags
|
||
|
|
- [x] ListMachineTags
|
||
|
|
- [x] GetMachineTag
|
||
|
|
- [x] DeleteMachineTag
|
||
|
|
- [x] DeleteMachineTags
|
||
|
|
- [x] DeleteMachine
|
||
|
|
- [ ] MachineAudit
|
||
|
|
- Analytics
|
||
|
|
- [ ] DescribeAnalytics
|
||
|
|
- [ ] ListInstrumentations
|
||
|
|
- [ ] GetInstrumentation
|
||
|
|
- [ ] GetInstrumentationValue
|
||
|
|
- [ ] GetInstrumentationHeatmap
|
||
|
|
- [ ] GetInstrumentationHeatmapDetails
|
||
|
|
- [ ] CreateInstrumentation
|
||
|
|
- [ ] DeleteInstrumentation
|
||
|
|
- Firewall Rules
|
||
|
|
- [x] ListFirewallRules
|
||
|
|
- [x] GetFirewallRule
|
||
|
|
- [x] CreateFirewallRule
|
||
|
|
- [x] UpdateFirewallRule
|
||
|
|
- [x] EnableFirewallRule
|
||
|
|
- [x] DisableFirewallRule
|
||
|
|
- [x] DeleteFirewallRule
|
||
|
|
- [ ] ListMachineFirewallRules
|
||
|
|
- [x] ListFirewallRuleMachines
|
||
|
|
- Fabrics
|
||
|
|
- [x] ListFabricVLANs
|
||
|
|
- [x] CreateFabricVLAN
|
||
|
|
- [x] GetFabricVLAN
|
||
|
|
- [x] UpdateFabricVLAN
|
||
|
|
- [x] DeleteFabricVLAN
|
||
|
|
- [x] ListFabricNetworks
|
||
|
|
- [x] CreateFabricNetwork
|
||
|
|
- [x] GetFabricNetwork
|
||
|
|
- [x] DeleteFabricNetwork
|
||
|
|
- Networks
|
||
|
|
- [x] ListNetworks
|
||
|
|
- [x] GetNetwork
|
||
|
|
- Nics
|
||
|
|
- [ ] ListNics
|
||
|
|
- [ ] GetNic
|
||
|
|
- [x] AddNic
|
||
|
|
- [x] RemoveNic
|
||
|
|
|
||
|
|
## Running Acceptance Tests
|
||
|
|
|
||
|
|
Acceptance Tests run directly against the Triton API, so you will need either a local installation or Triton or an account with Joyent in order to run them. The tests create real resources (and thus cost real money!)
|
||
|
|
|
||
|
|
In order to run acceptance tests, the following environment variables must be set:
|
||
|
|
|
||
|
|
- `TRITON_TEST` - must be set to any value in order to indicate desire to create resources
|
||
|
|
- `SDC_URL` - the base endpoint for the Triton API
|
||
|
|
- `SDC_ACCOUNT` - the account name for the Triton API
|
||
|
|
- `SDC_KEY_ID` - the fingerprint of the SSH key identifying the key
|
||
|
|
|
||
|
|
Additionally, you may set `SDC_KEY_MATERIAL` to the contents of an unencrypted private key. If this is set, the PrivateKeySigner (see above) will be used - if not the SSHAgentSigner will be used.
|
||
|
|
|
||
|
|
### Example Run
|
||
|
|
|
||
|
|
The verbose output has been removed for brevity here.
|
||
|
|
|
||
|
|
```
|
||
|
|
$ HTTP_PROXY=http://localhost:8888 \
|
||
|
|
TRITON_TEST=1 \
|
||
|
|
SDC_URL=https://us-sw-1.api.joyent.com \
|
||
|
|
SDC_ACCOUNT=AccountName \
|
||
|
|
SDC_KEY_ID=a4:c6:f3:75:80:27:e0:03:a9:98:79:ef:c5:0a:06:11 \
|
||
|
|
go test -v -run "TestAccKey"
|
||
|
|
=== RUN TestAccKey_Create
|
||
|
|
--- PASS: TestAccKey_Create (12.46s)
|
||
|
|
=== RUN TestAccKey_Get
|
||
|
|
--- PASS: TestAccKey_Get (4.30s)
|
||
|
|
=== RUN TestAccKey_Delete
|
||
|
|
--- PASS: TestAccKey_Delete (15.08s)
|
||
|
|
PASS
|
||
|
|
ok github.com/jen20/triton-go 31.861s
|
||
|
|
```
|
||
|
|
|
||
|
|
[4]: https://github.com/joyent/node-http-signature/blob/master/http_signing.md
|
||
|
|
[5]: https://godoc.org/github.com/joyent/go-triton/authentication
|
||
|
|
[6]: https://godoc.org/github.com/joyent/go-triton/authentication
|
||
|
|
[7]: https://github.com/hashicorp/go-errwrap
|