Initiates a connection to a target (for example, a managed node) for a Session Manager session. Returns a URL and token that can be used to open a WebSocket connection for sending input and receiving outputs.
Amazon Web Services CLI usage: start-session is an interactive command that requires the Session Manager plugin to be installed on the client machine making the call. For information, see Install the Session Manager plugin for the Amazon Web Services CLI in the Amazon Web Services Systems Manager User Guide.
Amazon Web Services Tools for PowerShell usage: Start-SSMSession isn't currently supported by Amazon Web Services Tools for PowerShell on Windows local machines.
Parameters:
-
target
(SessionTarget)
–
The managed node to connect to for the session.
-
document_name
(Optional[DocumentARN], default:
None
)
–
The name of the SSM document you want to use to define the type of session, input parameters, or preferences for the session. For example, SSM-SessionManagerRunShell. You can call the GetDocument API to verify the document exists before attempting to start a session. If no document name is provided, a shell to the managed node is launched by default. For more information, see Start a session in the Amazon Web Services Systems Manager User Guide.
-
reason
(Optional[SessionReason], default:
None
)
–
The reason for connecting to the instance. This value is included in the details for the Amazon CloudWatch Events event created when you start the session.
-
parameters
(Optional[SessionManagerParameters], default:
None
)
–
The values you want to specify for the parameters defined in the Session document. For more information about these parameters, see Create a Session Manager preferences document in the Amazon Web Services Systems Manager User Guide.
Raises:
-
InternalServerError
–
An error occurred on the server side.
-
InvalidDocument
–
The specified SSM document doesn't exist.
-
TargetNotConnected
–
The specified target managed node for the session isn't fully configured for use with Session Manager. For more information, see Setting up Session Manager in the Amazon Web Services Systems Manager User Guide. This error is also returned if you attempt to start a session on a managed node that is located in a different account or Region
-
UnknownServiceError
–
The service returned an error code this client does not model.
Source code in docs_src/capo_ssm/_services/ssm.py
| def start_session(
self,
target: "capo_ssm.types.session_target.SessionTarget",
*,
config_overrides: Optional[SSMClientConfig] = None,
document_name: Optional["capo_ssm.types.document_arn.DocumentARN"] = None,
reason: Optional["capo_ssm.types.session_reason.SessionReason"] = None,
parameters: Optional[
"capo_ssm.types.session_manager_parameters.SessionManagerParameters"
] = None,
) -> "capo_ssm.types.start_session_response.StartSessionResponse":
"""<p>Initiates a connection to a target (for example, a managed node) for a Session Manager session. Returns a URL and token that can be used to open a WebSocket connection for sending input and receiving outputs.</p> <note> <p>Amazon Web Services CLI usage: <code>start-session</code> is an interactive command that requires the Session Manager plugin to be installed on the client machine making the call. For information, see <a href="https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html">Install the Session Manager plugin for the Amazon Web Services CLI</a> in the <i>Amazon Web Services Systems Manager User Guide</i>.</p> <p>Amazon Web Services Tools for PowerShell usage: Start-SSMSession isn't currently supported by Amazon Web Services Tools for PowerShell on Windows local machines.</p> </note>
Args:
target: <p>The managed node to connect to for the session.</p>
document_name: <p>The name of the SSM document you want to use to define the type of session, input parameters, or preferences for the session. For example, <code>SSM-SessionManagerRunShell</code>. You can call the <a>GetDocument</a> API to verify the document exists before attempting to start a session. If no document name is provided, a shell to the managed node is launched by default. For more information, see <a href="https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-sessions-start.html">Start a session</a> in the <i>Amazon Web Services Systems Manager User Guide</i>.</p>
reason: <p>The reason for connecting to the instance. This value is included in the details for the Amazon CloudWatch Events event created when you start the session.</p>
parameters: <p>The values you want to specify for the parameters defined in the Session document. For more information about these parameters, see <a href="https://docs.aws.amazon.com/systems-manager/latest/userguide/getting-started-create-preferences-cli.html">Create a Session Manager preferences document</a> in the <i>Amazon Web Services Systems Manager User Guide</i>.</p>
Raises:
capo_ssm.errors.internal_server_error.InternalServerError: <p>An error occurred on the server side.</p>
capo_ssm.errors.invalid_document.InvalidDocument: <p>The specified SSM document doesn't exist.</p>
capo_ssm.errors.target_not_connected.TargetNotConnected: <p>The specified target managed node for the session isn't fully configured for use with Session Manager. For more information, see <a href="https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-getting-started.html">Setting up Session Manager</a> in the <i>Amazon Web Services Systems Manager User Guide</i>. This error is also returned if you attempt to start a session on a managed node that is located in a different account or Region</p>
capo_ssm.errors.UnknownServiceError: The service returned an error code this client does not model.
"""
def _handler(
req: "OperationRequest[capo_ssm.types.start_session_request.StartSessionRequest]",
) -> OperationResponse[
"capo_ssm.types.start_session_response.StartSessionResponse"
]:
import capo_ssm._operations.amazon_ssm.start_session
output, http_response = (
capo_ssm._operations.amazon_ssm.start_session.start_session(
req.options, req.input
)
)
return OperationResponse(output=output, response=http_response)
interceptors_, options_ = self.operation_options(
config_overrides, OperationLogging("StartSession")
)
input_: capo_ssm.types.start_session_request.StartSessionRequest = {
"target": target
}
if document_name is not None:
input_["document_name"] = document_name
if reason is not None:
input_["reason"] = reason
if parameters is not None:
input_["parameters"] = parameters
response = execute_pipeline(
OperationRequest(input=input_, options=options_),
handler=_handler,
interceptors=list(interceptors_),
)
response.response.close()
return response.output
|