Skip to content

SSM

Protocol: JSON 1.1 (X-Amz-Target: AmazonSSM.*) Endpoint: POST http://localhost:4566/

Supported Actions

Parameter Store

Action Description
PutParameter Create or update a parameter
GetParameter Get a single parameter by name, optionally name:version or name:label
GetParameters Get multiple parameters by name, with the same name:version and name:label selectors
GetParametersByPath Get all parameters under a path prefix
DeleteParameter Delete a parameter
DeleteParameters Delete multiple parameters
GetParameterHistory List all versions of a parameter
DescribeParameters List parameters with optional filters
LabelParameterVersion Attach a label to a specific version
UnlabelParameterVersion Remove labels from a specific version
AddTagsToResource Tag a parameter, a document (by name) or an association (by ID), picked by ResourceType
ListTagsForResource List tags on a parameter, a document or an association
RemoveTagsFromResource Remove tags from a parameter, a document or an association
PutResourcePolicy Attach or update the resource policy of an Advanced-tier parameter
GetResourcePolicies List the resource policy attached to a parameter
DeleteResourcePolicy Remove a parameter's resource policy
DescribePatchBaselines List AWS-owned predefined patch baselines (filter by OWNER, OPERATING_SYSTEM, NAME_PREFIX)
GetDefaultPatchBaseline Get the default patch baseline id for an operating system

CreateDocument and CreateAssociation keep their Tags. A document's tags are also returned in the DocumentDescription of CreateDocument, UpdateDocument and DescribeDocument, and in each ListDocuments entry. With IAM enforcement on, the tag calls are checked against the resource their ResourceType and ResourceId name: document/<name>, association/<id> or parameter/<name> without its leading /. CreateDocument is checked against document/<name>, and CreateAssociation against the association and the document/<name> its Name gives.

CreateAssociation also runs a document another account shared with the caller through ModifyDocumentPermission, given in Name by its ARN. With IAM enforcement on, the caller's policy must allow that ARN. A document the owner did not share is InvalidDocument.

GetParameters returns successful parameters alphabetically by Name, preserving the selected versions and labels.

DescribeParameters includes the stored parameter's ARN in each metadata entry, matching GetParameter. This applies to filtered and paginated results as well.

Retained flat-name parameters from older Floci versions expose canonical parameter/<name> ARNs on reads without a PutParameter overwrite. Normalization preserves the ARN's partition, region and account, along with the parameter's value, version, tags and history. Refresh cached Terraform outputs or policies that consumed the old malformed ARN; malformed policy resources do not grant access to the canonical ARN. The tagging actions still accept that old parameter<name> form as ResourceId when it names the request's partition, region and account, and read it as parameter/<name>.

PutParameter removes leading and trailing spaces from Name before it validates and stores it, as AWS does; a tab, newline or other whitespace is not removed. The name must then consist of letters, numbers, ., -, _ and the / separator, so a colon or an interior space fails with a ValidationException. Parameters stored under invalid names by older Floci versions can still be read, restored during CloudFormation rollback and deleted.

GetParameter, GetParameters, GetParameterHistory, LabelParameterVersion and GetParametersByPath remove leading and trailing ASCII spaces from the requested name or path before lookup, labeling or pagination. An interior space fails the complete request with ValidationException unless the name addresses a stored parameter, or the path contains stored descendants, in the caller's account and region. This exception preserves access to legacy Floci data; it does not allow new names with interior spaces. Secret-reference authorization uses the trimmed name; ARN, version and label selectors retain their normal scope and permission checks. Missing batch names are returned in InvalidParameters after this trimming. History and path pagination tokens work with either the padded or canonical name.

GetParametersByPath supports Type and KeyId entries in ParameterFilters, with Equals (the default) or BeginsWith. Values within one filter combine with OR; multiple filters combine with AND. Filtering also applies to public AMI parameters and respects Path, Recursive, and region selection. Unknown or missing keys and keys not allowed for this action are rejected with InvalidFilterKey. Label filters accept only Equals and return the stored versions carrying the requested labels, including older versions. Moving or removing a label changes subsequent results. The same OR/AND rules apply to label filters, and a version matching several requested labels appears only once. Type and KeyId filters match the labeled version's metadata. Public AMI parameters have no stored labels and are excluded from label queries. MaxResults and NextToken paginate the matching versions in name/version order; queries without a label filter continue to return the latest version of each parameter.

Run Command

Action Description
UpdateInstanceInformation Register or update an SSM agent record for an instance. Does not create an EC2 instance or register the container with IMDS (see Run Command Execution)
DescribeInstanceInformation List registered SSM managed instances
SendCommand Create command invocations for target instances
GetCommandInvocation Return a command invocation result
ListCommands List command records
ListCommandInvocations List command invocation records
CancelCommand Cancel pending or in-progress command invocations

ec2messages Agent Protocol

Action Description
GetMessages Agent polls for pending command messages
AcknowledgeMessage Agent acknowledges receipt of a command message
SendReply Agent reports command output and status

Run Command Execution

SendCommand supports the AWS-RunShellScript document. For EC2 instances launched by Floci in real Docker mode, Floci creates the command invocation, returns the command response, and then runs the script asynchronously inside the target instance container. Callers observe completion through GetCommandInvocation. stdout, stderr, response code, start time, and end time are recorded on the invocation.

For public SendCommand, set TimeoutSeconds to a delivery/start allowance from 30 to 2,592,000 seconds. The default is 3,600 seconds. Floci does not automatically expire commands waiting for an agent, so a command that is never delivered can remain pending indefinitely. The document's execution allowance and internal CodeDeploy hook budgets are separate.

If the target is not a Floci EC2 container, or if the document is not supported for direct execution, Floci falls back to the SSM agent polling flow. In that mode, SendCommand queues an ec2messages payload and the invocation completes after an agent calls SendReply.

Background execution retains the issuing account and region. Agent queues and message correlations use that same account, region and instance identity; polling or completing a message from another account or region leaves the owner's work untouched. Pending messages remain in memory and are lost on restart.

Managed instance registration is independent of EC2 and IMDS

Registering a container's SSM agent with UpdateInstanceInformation only creates the managed instance record. It does not create an EC2 instance, does not install the link-local 169.254.169.254 proxy in the container, and does not register the container with the EC2 IMDS server. A container that was only registered with SSM therefore has no working IMDS endpoint and no instance profile credentials, and SendCommand against it uses the agent polling flow rather than direct execution.

To get a container that both answers IMDS and runs SendCommand directly, launch it with EC2 RunInstances first and then register that same container's SSM agent. Floci logs a warning when an agent registers from a container that is not backed by a Floci EC2 instance.

Direct command output follows the AWS inline output limits: first 24,000 characters of stdout and first 8,000 characters of stderr. Commands that exceed their execution budget are constrained inside the target container when the container has the timeout command available, and terminal timeout results are marked TimedOut with StatusDetails set to Execution Timed Out; commands with nonzero exit codes are marked Failed.

Shell command timeout budgets

For public SendCommand requests using the exact AWS-RunShellScript document name, TimeoutSeconds is the delivery/start allowance. Parameters.executionTimeout is a separate execution allowance, defaulting to 3600 seconds and accepting one decimal string from 1 to 172800. The direct worker uses this execution allowance; agent payloads retain the public document's 3600-second default and carry an explicit parameter unchanged.

Command.TimeoutSeconds still reports the delivery allowance. ExpiresAfter includes both allowances for these shell requests. This corrects metadata and execution budgets; it does not add automatic delivery expiration, restart recovery, cleanup retries or late-start fencing. Internal CodeDeploy hook budgets and non-shell document handling keep their existing behavior. Missing or empty commands, malformed shell parameter wire shapes and invalid execution limits are refused before command creation with InvalidParameters/HTTP400. This is Floci's chosen mapping; exact AWS error wording and empty-list normalization were not observed live. Other document parameters and delivery-timeout coercion/upper-bound handling are not a complete document-schema implementation.

Configuration

Variable Default Description
FLOCI_SERVICES_SSM_ENABLED true Enable or disable the service
FLOCI_SERVICES_SSM_MAX_PARAMETER_HISTORY 5 Number of parameter versions retained per parameter
FLOCI_STORAGE_SERVICES_SSM_MODE (global default) Storage mode override for SSM (memory, persistent, hybrid, wal)
FLOCI_STORAGE_SERVICES_SSM_FLUSH_INTERVAL_MS 5000 Flush interval for hybrid/wal storage modes (milliseconds)

Examples

export AWS_ENDPOINT_URL=http://localhost:4566

# Store parameters
aws ssm put-parameter --endpoint-url $AWS_ENDPOINT_URL \
  --name /app/db/host --value "localhost" --type String

aws ssm put-parameter --endpoint-url $AWS_ENDPOINT_URL \
  --name /app/db/password --value "secret" --type SecureString

# Retrieve
aws ssm get-parameter --endpoint-url $AWS_ENDPOINT_URL \
  --name /app/db/host

aws ssm get-parameters-by-path --endpoint-url $AWS_ENDPOINT_URL \
  --path /app/ --recursive

# Delete
aws ssm delete-parameter --endpoint-url $AWS_ENDPOINT_URL \
  --name /app/db/host

# Run a shell command on a Floci EC2 instance
aws ssm send-command --endpoint-url $AWS_ENDPOINT_URL \
  --instance-ids i-0123456789abcdef0 \
  --document-name AWS-RunShellScript \
  --parameters commands='["echo hello"]'

Public AMI Parameters

AWS publishes AMI id lookup parameters under /aws/service/ami-amazon-linux-latest/ and EKS optimized node AMI lookup parameters under /aws/service/eks/optimized-ami/ in every account, and tools such as Terraform, Karpenter and eksctl read them without any setup. Floci answers the documented Amazon Linux 2 and Amazon Linux 2023 names from its EC2 image catalog across supported architectures and Kubernetes versions, so GetParameter, GetParameters and GetParametersByPath resolve them to the catalog's AMI ids. As on AWS they are read-only and belong to no account, so they do not appear in DescribeParameters.

Floci also answers the Amazon Linux 2023 ECS optimized AMI recommended/image_id and recommended parameters under /aws/service/ecs/optimized-ami/. The image ID points to the catalog's x86_64 Amazon Linux 2023 image. The recommended value is JSON with the matching image ID and name; its ECS agent and runtime versions are unknown because the catalog image is synthetic and does not represent an installed ECS runtime.

Canonical's Ubuntu Server AMI parameters under /aws/service/canonical/ubuntu/server/ resolve too, by version or codename: 24.04/noble (amd64 and arm64, ebs-gp3) and 22.04/jammy and 20.04/focal (amd64, ebs-gp2), each at stable/current.

aws ssm get-parameter --name /aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-x86_64
aws ssm get-parameter --name /aws/service/eks/optimized-ami/1.31/amazon-linux-2023/x86_64/standard/recommended/image_id
aws ssm get-parameter --name /aws/service/ecs/optimized-ami/amazon-linux-2023/recommended/image_id
aws ssm get-parameter --name /aws/service/canonical/ubuntu/server/24.04/stable/current/amd64/hvm/ebs-gp3/ami-id

Secrets Manager References

GetParameter and GetParameters answer /aws/reference/secretsmanager/<secret-id> from Secrets Manager, so an application, an ECS task secret or a CodeBuild parameter-store variable can read a secret through Parameter Store. The answer is a SecureString with the secret's value and ARN and Version 0, and SourceResult carries the Secrets Manager GetSecretValue result as a JSON string, without secretBinary for a binary secret. A :<version-id> or :<staging-label> suffix, such as :AWSPREVIOUS, selects a version and is echoed as Selector. As on AWS, WithDecryption must be true, and a missing secret is ParameterNotFound; GetParameters lists a reference it cannot answer in InvalidParameters. With IAM enforcement on, the caller also needs secretsmanager:GetSecretValue on the secret, and a refusal fails the whole call with a ValidationException, as it does on AWS.

aws ssm get-parameter --name /aws/reference/secretsmanager/my-app/api-key --with-decryption

Parameter ARNs

A parameter's ARN is arn:<partition>:ssm:<region>:<account>:parameter/<name without leading slash> for both a top-level name such as db-host and a path such as /app/db/host, as on AWS. The CloudFormation Arn attribute of an AWS::SSM::Parameter is the same ARN, and AddTagsToResource, ListTagsForResource and RemoveTagsFromResource accept it as ResourceId when it names the request's partition, region and account; an ARN naming another one fails with InvalidResourceId. An ECS container secret's valueFrom accepts it too.

GetParameter and GetParameters accept the returned ARN, optionally followed by :version or :label, for parameters in the caller's account and request region. Batch reads keep unresolved inputs in InvalidParameters in their original form. An ARN whose resource is parameter//<name> names //<name>, never /<name>. ARNs naming another account, region or partition never resolve to a same-name local parameter. Cross-account shared parameters are not modeled. Secrets Manager references continue to use /aws/reference/secretsmanager/<secret-id>, not a parameter ARN.

Parameter Resource Policies

PutResourcePolicy, GetResourcePolicies and DeleteResourcePolicy take the parameter ARN as ResourceArn. Only an Advanced-tier parameter can have a policy, and it has at most one; a SecureString encrypted with the default aws/ssm key cannot have one. PutResourcePolicy returns the policy's PolicyId and PolicyHash; updating or deleting the policy takes both, and a hash that is no longer current fails with ResourcePolicyConflictException. A policy over 1024 bytes fails with ResourcePolicyLimitExceededException, and a document that is not a JSON object with MalformedResourcePolicyDocumentException. An overwriting PutParameter keeps the policy, and is refused with ResourcePolicyInvalidParameterException when it would leave the policy on a parameter that could not take one; deleting the parameter removes it. With IAM enforcement on, the three actions are checked against the parameter ResourceArn names. Floci stores the policy but does not evaluate it against callers or create the AWS RAM resource share AWS makes for a shared parameter.

Parameter Types

All AWS parameter types are accepted: String, StringList, SecureString.

PutParameter encrypts a SecureString with Floci's KMS under the parameter's key (alias/aws/ssm when none was given), with the encryption context PARAMETER_ARN set to the parameter's ARN, as AWS does. A read without WithDecryption (GetParameter, GetParameters, GetParametersByPath, GetParameterHistory) returns that ciphertext, the same one on every read of a version, and KMS Decrypt with that context returns the plaintext. With WithDecryption the plaintext is returned.

Note

The encryption applies to what the API returns, not to storage: Floci saves each SecureString version's plaintext alongside its ciphertext, so the plaintext stays readable in the persisted state files.

A KeyId that Floci's KMS cannot use, which AWS would refuse on PutParameter, is accepted, and such a parameter is returned unencrypted. So is a value over KMS's 4096-byte limit, and a parameter version stored before Floci encrypted SecureString values.

AWS encrypts every Advanced SecureString with the AWS Encryption SDK, so its value is the SDK's encrypted message. Floci encrypts an Advanced value up to 4096 bytes with a plain KMS Encrypt instead, the same as a Standard one.

Parameter Store Change events

Like AWS, Floci publishes a Parameter Store Change event (source: aws.ssm) to the account's default EventBridge bus after a successful parameter write, so a rule matching aws.ssm fires from Parameter Store activity. resources holds the parameter ARN, and the event carries the account and region of the call.

Call Events detail
PutParameter, new name one Create operation, name, type, and description when set
PutParameter overwriting an existing name one Update, even when the value is unchanged as for Create
DeleteParameter one Delete as for Create
DeleteParameters one Delete per deleted name, none for a missing name as for Create
LabelParameterVersion one LabelParameterVersion per valid label it attaches or moves as for Create, from the labelled version, plus label, fromVersion (the version the label left as a string, "" for a new label) and toVersion
UnlabelParameterVersion one UnlabelParameterVersion when it removes a label, none otherwise as for Create, from the unlabelled version, plus labels (the labels removed), fromVersion (that version as a string) and toVersion ("")

Parameters a CloudFormation stack creates or deletes publish the same events. A call that fails, such as a PutParameter on an existing name without Overwrite, publishes nothing, and so do AddTagsToResource, a label already on the requested version and an invalid label. Publishing is best effort: a delivery failure is logged and never fails or undoes the write.