Documentation
¶
Overview ¶
Package builder (aka "commands builder") contains a set of functions and types for working with Ceph's dynamic command framework dynamically.
Ceph Command Basics ¶
Ever wonder how the Ceph project's `ceph` command works? Commands like `ceph osd df`, `ceph pg ls`, or even `ceph orch ls`? Ceph's core protocol is RADOS and Ceph's RADOS library provides API functions such as `rados_mon_command`, `rados_mgr_command`, `rados_osd_command` and so on. The go-ceph rados package implements wrapper functions like `MonCommand` and `MgrCommand`. These API functions serve as the fundamental building-blocks of Ceph's command line interface.
As an example the function signature of MonCommand from the rados library is as follows:
func (c *Conn) MonCommand(args []byte) ([]byte, string, error) {
...
}
The input to this function is a bytes slice. The output is a byte slice representing the server's response, a status string, and an error. The error can be a protocol error or an error response from the server.
To invoke a particular command API on the server the input bytes slice must contain a JSON formatted object containing the command and any parameters. The command itself is formatted as a single space-separated string using the "prefix" key and other parameters are a passed as keys and values in the JSON object. For example the command `ceph osd df tree --filter=hdd` is equivalent to the following JSON:
{
"prefix": "osd df",
"output_method": "tree",
"filter": "hdd"
}
If you know what parameters are expected it's often easy to construct some static JSON or use a `map[string]string` and `json.Marshal` to create a parameterized call.
Knowing what commands exist and what input variables are available is where this package comes in. Ceph provides an API to query what is available `{"prefix": "get_command_descriptions"}` and this package aims to make that more convenient to use.
Note that the output of the commands is highly dependent on the command being called. Some commands emit human readable text, others JSON, etc. In some cases, the format of the command's output can be requested by specifying a "format" key and value such as "json" or "yaml". However, a command may not support a particular format and ignore the hint. Also, unlike the command descriptions Ceph doesn't provide general structured descriptions of the returned values even when emitting a machine-parseable format like JSON. You may want to keep the documentation handy for that phase.
Introducing go-ceph's Command Builder Package ¶
The go-ceph library already provides many packages that wrap Ceph commands such as `rbd/admin`, `cephfs/admin`, `common/admin/nfs` and so on. Our convention is to call these admin packages because the APIs are typically needed for administering a Ceph cluster rather than just storing/retrieving data from it.
But there are cases where we have not covered a set of APIs with a dedicated package or there might be cases were you want to do things differently. This commands builder package allows you to use the rados APIs to query for the command descriptions and optionally use those descriptions to build the command JSON.
Querying Command Descriptions ¶
This library currently provides two sets of APIs for querying command descriptions. For querying the Ceph MON:
QueryMonJSON(m ccom.MonCommander) ([]byte, error) QueryMonDescriptions(m ccom.MonCommander) (CommandDescriptions, error)
For querying the Ceph MGR:
QueryMgrJSON(m ccom.MgrCommander) ([]byte, error) QueryMgrDescriptions(m ccom.MgrCommander) (CommandDescriptions, error)
The functions ending in ...JSON always return the raw JSON text in case you want to do custom parsing or perhaps just want to dump the unedited JSON to the output. The Descriptions functions will parse the JSON automatically and return a helper type that stores the descriptions and provides methods for searching for matching commands.
For example to query the MON for commands starting with "osd" one can execute:
cde, err := QueryMonDescriptions(radosConn)
// handle err...
for _, cmd := range cde.Find("osd") {
fmt.Printf("osd command: %s\n", cmd.PrefixString())
}
Each command description contains a signature that can be broken down into the fixed prefix strings and the variables. Each [SignatureVariable] contains fields that describe what type of input is expected, and sometimes a bit about what the allowed values are.
Building Commands ¶
In addition to simply getting information about the commands and their arguments the Builder type and Ceph argument types (those matching the CephArgumentType interface) can be used to dynamically construct a Values map that will be serialized to JSON. The `Apply` function can be used to convert a sequence of strings and/or a mapping of keyword-value pairs to a ceph command.
NOTE: Not all types are fully implemented. Consider filing an issue or contributing a patch if you need one.
Non-Goals ¶
Note that this package just aims to provide components one can use to dynamically construct Ceph command inputs without doing it all yourself. It doesn't aim to be a replacement for the `ceph` command. It doesn't aim to be a fully featured tool for building an alternative command line parser for ceph. One might use it as a component of such a thing, or maybe a GUI, but that's all it aims to be - a toolkit rather than a complete solution.
Index ¶
- Constants
- func QueryMgrJSON(m ccom.MgrCommander) ([]byte, error)
- func QueryMonJSON(m ccom.MonCommander) ([]byte, error)
- type Builder
- type CephArgumentType
- type CephBool
- type CephChoices
- func (t *CephChoices) Check(v any) error
- func (t *CephChoices) Choices() map[string]bool
- func (t *CephChoices) Convert(v any) (any, error)
- func (t *CephChoices) Name() string
- func (t *CephChoices) Set(data map[string]any, v any) error
- func (*CephChoices) TypeName() string
- func (t *CephChoices) Validate(data map[string]any) error
- type CephFloat
- type CephInt
- type CephMultiArgumentType
- type CephOSDName
- type CephObjectName
- type CephPGID
- type CephPoolName
- type CephRepeatedArg
- type CephScalarArgumentType
- type CephString
- type CephTypeFunc
- type CephUnknownType
- type CommandDescriptions
- type Description
- type SignatureElement
- type SignatureVar
Constants ¶
const ( CephTypeBool = "CephBool" CephTypeChoices = "CephChoices" CephTypeEntityAddr = "CephEntityAddr" CephTypeFilePath = "CephFilepath" CephTypeFloat = "CephFloat" CephTypeFragment = "CephFragment" CephTypeInt = "CephInt" CephTypeIPAddr = "CephIPAddr" CephTypeName = "CephName" CephTypeObjectName = "CephObjectname" CephTypeOSDName = "CephOsdName" CephTypePGID = "CephPgid" CephTypePoolName = "CephPoolname" CephTypeSocketPath = "CephSocketpath" CephTypeString = "CephString" CephTypeUUID = "CephUUID" )
CephTypeX constants naming all currently known variable argument types.
Variables ¶
This section is empty.
Functions ¶
func QueryMgrJSON ¶
func QueryMgrJSON(m ccom.MgrCommander) ([]byte, error)
QueryMgrJSON makes a request to the Ceph MGR to describe the commands that the service knows about. This function returns the response as raw JSON encoded bytes.
func QueryMonJSON ¶
func QueryMonJSON(m ccom.MonCommander) ([]byte, error)
QueryMonJSON makes a request to the Ceph MON to describe the commands that the service knows about. This function returns the response as raw JSON encoded bytes.
Types ¶
type Builder ¶
type Builder struct {
Values map[string]any
Description Description
GetType CephTypeFunc
}
Builder objects are used to construct command inputs that interact with Ceph APIs such as MgrCommand, MonCommand, and so forth. This type provides a MarshalJSON method that will return JSON encoded bytes that can be passed as the first argument to these RADOS APIs. The MarshalJSON uses the command description to produce argument types that validate the contents of the Values map. The Values map is public so that you can directly manipulate the contents in unplanned ways and customize what gets encoded in the final JSON. You can also customize the ceph types returned by setting an alternative GetType attribute. By default, this uses the BindArgumentType function but you can replace or re-use this function to return customized CephArgumentType values to fit your needs.
func NewBuilder ¶
func NewBuilder(d Description) *Builder
NewBuilder returns a new command builder given a Description of ceph command.
func (*Builder) Apply ¶
Apply takes string argument values, in either a slice (linear) or map (named) form and, using the known argument types, converts the values and stores the results in the builder's Values map.
NB. This function doesn't handle repeat arguments (n:N) other than in the args slice and then only at the end of the slice. This function is meant to serve as a simple example for mapping argument values into a call to MonCommand/MgrCommand/etc. not implement everything the standard `ceph` command can do.
func (*Builder) Arguments ¶
func (b *Builder) Arguments() []CephArgumentType
Arguments returns a slice of all the ceph argument types known to this builder.
func (*Builder) ArgumentsMap ¶
func (b *Builder) ArgumentsMap() map[string]CephArgumentType
ArgumentsMap returns a map of argument names to the various ceph argument types known to this builder.
func (*Builder) MarshalJSON ¶
MarshalJSON returns the builder's Values map as JSON encoded bytes or an error if the Values don't validate or marshal to JSON.
type CephArgumentType ¶
type CephArgumentType interface {
TypeName() string
Name() string
Set(map[string]any, any) error
Validate(map[string]any) error
}
CephArgumentType represents types that can be used to manage argument values for a Ceph command.
func BindArgumentType ¶
func BindArgumentType(sv *SignatureVar) CephArgumentType
BindArgumentType returns a CephArgumentType bound to the given SignatureVar.
type CephBool ¶
type CephBool struct {
// contains filtered or unexported fields
}
CephBool arguments represent boolean valued arguments.
func (*CephBool) Check ¶
Check that a given value meets requirements for this argument. Returns an error if this value fails the check.
func (*CephBool) Convert ¶
Convert an any value into a valid underlying type for later serialization. Returns new type as any or error if conversion fails.
func (*CephBool) Set ¶
Set the given value into the map ensuring that the value is of the correct underlying type. If the type is not valid returns an error.
type CephChoices ¶
type CephChoices struct {
// contains filtered or unexported fields
}
CephChoices arguments are basically strings constrained to certain allowed values.
func (*CephChoices) Check ¶
func (t *CephChoices) Check(v any) error
Check that a given value meets requirements for this argument. Returns an error if this value fails the check.
func (*CephChoices) Choices ¶
func (t *CephChoices) Choices() map[string]bool
Choices returns the allowed values for this argument as map of strings to bools.
func (*CephChoices) Convert ¶
func (t *CephChoices) Convert(v any) (any, error)
Convert an any value into a valid underlying type for later serialization. Returns new type as any or error if conversion fails.
func (*CephChoices) Name ¶
func (t *CephChoices) Name() string
Name returns the name of this ceph argument.
func (*CephChoices) Set ¶
func (t *CephChoices) Set(data map[string]any, v any) error
Set the given value into the map ensuring that the value is of the correct underlying type. If the type is not valid returns an error.
func (*CephChoices) TypeName ¶
func (*CephChoices) TypeName() string
TypeName returns the name of this ceph argument type.
type CephFloat ¶
type CephFloat struct {
// contains filtered or unexported fields
}
CephFloat arguments represent floating-point valued arguments.
func (*CephFloat) Check ¶
Check that a given value meets requirements for this argument. Returns an error if this value fails the check.
func (*CephFloat) Convert ¶
Convert an any value into a valid underlying type for later serialization. Returns new type as any or error if conversion fails.
func (*CephFloat) Set ¶
Set the given value into the map ensuring that the value is of the correct underlying type. If the type is not valid returns an error.
type CephInt ¶
type CephInt struct {
// contains filtered or unexported fields
}
CephInt arguments represent integer valued arguments.
func (*CephInt) Check ¶
Check that a given value meets requirements for this argument. Returns an error if this value fails the check.
func (*CephInt) Convert ¶
Convert an any value into a valid underlying type for later serialization. Returns new type as any or error if conversion fails.
func (*CephInt) Set ¶
Set the given value into the map ensuring that the value is of the correct underlying type. If the type is not valid returns an error.
type CephMultiArgumentType ¶
CephMultiArgumentType represents types that can be used to manage multiple (slices of) values for a single argument in a Ceph command.
type CephOSDName ¶
type CephOSDName struct {
CephString
}
CephOSDName arguments represent strings limited to naming ceph OSDs.
func (*CephOSDName) TypeName ¶
func (*CephOSDName) TypeName() string
TypeName returns the name of this ceph argument type.
type CephObjectName ¶
type CephObjectName struct {
CephString
}
CephObjectName arguments represent strings limited to naming ceph objects.
func (*CephObjectName) TypeName ¶
func (*CephObjectName) TypeName() string
TypeName returns the name of this ceph argument type.
type CephPGID ¶
type CephPGID struct {
CephString
}
CephPGID arguments represent strings limited to identifying ceph PGs.
type CephPoolName ¶
type CephPoolName struct {
CephString
}
CephPoolName arguments represent strings limited to naming ceph pools.
func (*CephPoolName) TypeName ¶
func (*CephPoolName) TypeName() string
TypeName returns the name of this ceph argument type.
type CephRepeatedArg ¶
type CephRepeatedArg struct {
// contains filtered or unexported fields
}
CephRepeatedArg is a special argument type that wraps a more basic (scalar) type allowing it to be repeated in the argument sequence.
func (*CephRepeatedArg) Append ¶
func (t *CephRepeatedArg) Append(data map[string]any, v any) error
Append the given value onto a slice in the data map. Works like Set but assumes a single value of the desired type (string for CephString, int or string-with-int-value for CephInt).
func (*CephRepeatedArg) Name ¶
func (t *CephRepeatedArg) Name() string
Name returns the name of this ceph argument.
func (*CephRepeatedArg) Set ¶
func (t *CephRepeatedArg) Set(data map[string]any, v any) error
Set the given value into the map ensuring that the value is of the correct underlying type. If the type is not valid returns an error.
func (*CephRepeatedArg) TypeName ¶
func (t *CephRepeatedArg) TypeName() string
TypeName returns the name of this ceph argument type.
type CephScalarArgumentType ¶
type CephScalarArgumentType interface {
CephArgumentType
Convert(v any) (any, error)
Check(v any) error
}
CephScalarArgumentType represents types that can be used to manage a single argument value for a Ceph command.
type CephString ¶
type CephString struct {
// contains filtered or unexported fields
}
CephString arguments represent arbitrary strings.
func (*CephString) Check ¶
func (t *CephString) Check(v any) error
Check that a given value meets requirements for this argument. Returns an error if this value fails the check.
func (*CephString) Convert ¶
func (*CephString) Convert(v any) (any, error)
Convert an any value into a valid underlying type for later serialization. Returns new type as any or error if conversion fails.
func (*CephString) Name ¶
func (t *CephString) Name() string
Name returns the name of this ceph argument.
func (*CephString) Set ¶
func (t *CephString) Set(data map[string]any, v any) error
Set the given value into the map ensuring that the value is of the correct underlying type. If the type is not valid returns an error.
func (*CephString) TypeName ¶
func (*CephString) TypeName() string
TypeName returns the name of this ceph argument type.
type CephTypeFunc ¶
type CephTypeFunc func(*SignatureVar) CephArgumentType
CephTypeFunc signatures describe a function that can provide a CephArgumentType instance given a SignatureVar object. This is used to customize argument type look ups if needed.
type CephUnknownType ¶
type CephUnknownType struct {
// contains filtered or unexported fields
}
CephUnknownType is a placeholder type for other unknown or unimplemented types.
func (*CephUnknownType) Name ¶
func (t *CephUnknownType) Name() string
Name returns the name of this ceph argument.
func (*CephUnknownType) Set ¶
func (t *CephUnknownType) Set(map[string]any, any) error
Set the given value into the map ensuring that the value is of the correct underlying type. If the type is not valid returns an error.
func (*CephUnknownType) TypeName ¶
func (*CephUnknownType) TypeName() string
TypeName returns the name of this ceph argument type.
type CommandDescriptions ¶
type CommandDescriptions struct {
Entries []Description
}
CommandDescriptions is a wrapper type to encapsulate the ceph commands known to a particular process. Methods such as Match or Find can be used to narrow down commands to a set with matching prefix terms.
func QueryMgrDescriptions ¶
func QueryMgrDescriptions(m ccom.MgrCommander) (CommandDescriptions, error)
QueryMgrDescriptions makes a request to the Ceph MGR to describe the commands that the service knows about. This function returns the response as a CommandDescriptions object.
func QueryMonDescriptions ¶
func QueryMonDescriptions(m ccom.MonCommander) (CommandDescriptions, error)
QueryMonDescriptions makes a request to the Ceph MON to describe the commands that the service knows about. This function returns the response as a CommandDescriptions object.
func (*CommandDescriptions) Find ¶
func (cd *CommandDescriptions) Find(n ...string) []Description
Find returns all command Descriptions that have full or partially matching prefix strings. This is like Match but uses variable arguments instead of a slice for convenience in code where you know what command you intend to call. For example: `matches = cd.Find("osd", "rm")`.
func (*CommandDescriptions) Match ¶
func (cd *CommandDescriptions) Match(terms []string) []Description
Match returns all command Descriptions that have full or partially matching prefix strings. For example, passing `[]string{"osd"}` will return a slice with all commands where the first prefix term is "osd". Passing `[]string{"osd", "ls"}` will return a slice with all commands where the first two prefix terms are "osd" and "ls".
func (*CommandDescriptions) UnmarshalJSON ¶
func (cd *CommandDescriptions) UnmarshalJSON(data []byte) error
UnmarshalJSON decodes JSON data into a CommandDescriptions object.
type Description ¶
type Description struct {
Key string
Sig []*SignatureElement `json:"sig"`
Help string `json:"help"`
Module string `json:"module"`
Perm string `json:"perm"`
Flags uint64 `json:"flags"`
}
Description represents a single ceph command known to a process such as the Ceph MON, Ceph MGR, or so on.
func (Description) Prefix ¶
func (d Description) Prefix() []string
Prefix returns the static strings in the signature of a command as a slice of strings.
func (Description) PrefixString ¶
func (d Description) PrefixString() string
PrefixString returns the static strings in the signature of a command as a single space separated string.
func (Description) Variables ¶
func (d Description) Variables() []*SignatureVar
Variables returns the variable components in a ceph command signature in a slice.
type SignatureElement ¶
type SignatureElement struct {
Static string
Variable *SignatureVar
}
SignatureElement describes a single element in a Ceph command description. It can either be a static or fixed string (that will be part of the command prefix) or a variable input.
func (*SignatureElement) UnmarshalJSON ¶
func (se *SignatureElement) UnmarshalJSON(data []byte) error
UnmarshalJSON decodes JSON into a SignatureElement.
type SignatureVar ¶
type SignatureVar struct {
Name string `json:"name"`
Type string `json:"type"`
Req *bool `json:"req"`
Choices string `json:"strings"`
Repeat string `json:"n"`
}
SignatureVar describes variable arguments in a Ceph command description.
func (SignatureVar) Required ¶
func (sv SignatureVar) Required() bool
Required returns true if the variable is required.
Source Files