Skip to content

Commit 9572bd8

Browse files
Dingane Hlalukuborisstoyanov
Dingane Hlaluku
authored and
borisstoyanov
committed
diagnostics: new diagnostics admin API for system VMs (apache#2721)
This is a new feature for CS that allows Admin users improved troubleshooting of network issues in CloudStack hosted networks. Description: For troubleshooting purposes, CloudStack administrators may wish to execute network utility commands remotely on system VMs, or request system VMs to ping/traceroute/arping to specific addresses over specific interfaces. An API command to provide such functionalities is being developed without altering any existing APIs. The targeted system VMs for this feature are the Virtual Router (VR), Secondary Storage VM (SSVM) and the Console Proxy VM (CPVM). FS: https://cwiki.apache.org/confluence/display/CLOUDSTACK/CloudStack+Remote+Diagnostics+API ML discussion: https://markmail.org/message/xt7owmb2c6iw7tva
1 parent 2502aec commit 9572bd8

File tree

19 files changed

+1377
-28
lines changed

19 files changed

+1377
-28
lines changed

‎.travis.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ env:
3838
matrix:
3939
# Keep the TESTS sorted by name and grouped by type
4040
- TESTS="smoke/test_certauthority_root"
41-
41+
4242
- TESTS="smoke/test_accounts
4343
smoke/test_affinity_groups
4444
smoke/test_affinity_groups_projects
@@ -47,6 +47,7 @@ env:
4747
smoke/test_deploy_vm_root_resize
4848
smoke/test_deploy_vm_with_userdata
4949
smoke/test_deploy_vms_with_varied_deploymentplanners
50+
smoke/test_diagnostics
5051
smoke/test_disk_offerings
5152
smoke/test_dynamicroles
5253
smoke/test_global_settings

‎api/src/main/java/org/apache/cloudstack/api/ApiConstants.java‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -719,6 +719,11 @@ public class ApiConstants {
719719
public static final String LAST_ANNOTATED = "lastannotated";
720720
public static final String LDAP_DOMAIN = "ldapdomain";
721721

722+
public static final String STDOUT = "stdout";
723+
public static final String STDERR = "stderr";
724+
public static final String EXITCODE = "exitcode";
725+
public static final String TARGET_ID = "targetid";
726+
722727
public enum HostDetails {
723728
all, capacity, events, stats, min;
724729
}

‎api/src/main/java/org/apache/cloudstack/api/command/admin/diagnostics/RunDiagnosticsCmd.java‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
// Licensed to the Apache Software Foundation (ASF) under one
2+
// or more contributor license agreements. See the NOTICE file
3+
// distributed with this work for additional information
4+
// regarding copyright ownership. The ASF licenses this file
5+
// to you under the Apache License, Version 2.0 (the
6+
// "License"); you may not use this file except in compliance
7+
// with the License. You may obtain a copy of the License at
8+
//
9+
// http://www.apache.org/licenses/LICENSE-2.0
10+
//
11+
// Unless required by applicable law or agreed to in writing,
12+
// software distributed under the License is distributed on an
13+
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
// KIND, either express or implied. See the License for the
15+
// specific language governing permissions and limitations
16+
// under the License.
17+
package org.apache.cloudstack.api.command.admin.diagnostics;
18+
19+
import com.cloud.exception.InsufficientCapacityException;
20+
import com.cloud.exception.ResourceUnavailableException;
21+
import com.cloud.user.Account;
22+
import com.cloud.vm.VirtualMachine;
23+
import org.apache.cloudstack.acl.RoleType;
24+
import org.apache.cloudstack.api.APICommand;
25+
import org.apache.cloudstack.api.ApiArgValidator;
26+
import org.apache.cloudstack.api.ApiConstants;
27+
import org.apache.cloudstack.api.ApiErrorCode;
28+
import org.apache.cloudstack.api.BaseCmd;
29+
import org.apache.cloudstack.api.Parameter;
30+
import org.apache.cloudstack.api.ServerApiException;
31+
import org.apache.cloudstack.api.response.RunDiagnosticsResponse;
32+
import org.apache.cloudstack.api.response.SystemVmResponse;
33+
import org.apache.cloudstack.context.CallContext;
34+
import org.apache.cloudstack.diagnostics.DiagnosticsService;
35+
import org.apache.cloudstack.diagnostics.DiagnosticsType;
36+
import org.apache.commons.collections.CollectionUtils;
37+
import org.apache.log4j.Logger;
38+
39+
import javax.inject.Inject;
40+
import java.util.Collections;
41+
import java.util.Map;
42+
43+
@APICommand(name = RunDiagnosticsCmd.APINAME, responseObject = RunDiagnosticsResponse.class, entityType = {VirtualMachine.class},
44+
responseHasSensitiveInfo = false,
45+
requestHasSensitiveInfo = false,
46+
description = "Execute network-utility command (ping/arping/tracert) on system VMs remotely",
47+
authorized = {RoleType.Admin},
48+
since = "4.12.0.0")
49+
public class RunDiagnosticsCmd extends BaseCmd {
50+
private static final Logger LOGGER = Logger.getLogger(RunDiagnosticsCmd.class);
51+
public static final String APINAME = "runDiagnostics";
52+
53+
@Inject
54+
private DiagnosticsService diagnosticsService;
55+
56+
/////////////////////////////////////////////////////
57+
//////////////// API parameters /////////////////////
58+
/////////////////////////////////////////////////////
59+
@Parameter(name = ApiConstants.TARGET_ID, type = CommandType.UUID, required = true, entityType = SystemVmResponse.class,
60+
validations = {ApiArgValidator.PositiveNumber},
61+
description = "The ID of the system VM instance to diagnose")
62+
private Long id;
63+
64+
@Parameter(name = ApiConstants.IP_ADDRESS, type = CommandType.STRING, required = true,
65+
validations = {ApiArgValidator.NotNullOrEmpty},
66+
description = "The IP/Domain address to test connection to")
67+
private String address;
68+
69+
@Parameter(name = ApiConstants.TYPE, type = CommandType.STRING, required = true,
70+
validations = {ApiArgValidator.NotNullOrEmpty},
71+
description = "The system VM diagnostics type valid options are: ping, traceroute, arping")
72+
private String type;
73+
74+
@Parameter(name = ApiConstants.PARAMS, type = CommandType.STRING,
75+
authorized = {RoleType.Admin},
76+
description = "Additional command line options that apply for each command")
77+
private String optionalArguments;
78+
79+
/////////////////////////////////////////////////////
80+
/////////////////// Accessors ///////////////////////
81+
/////////////////////////////////////////////////////
82+
public Long getId() {
83+
return id;
84+
}
85+
86+
public String getAddress() {
87+
return address;
88+
}
89+
90+
public DiagnosticsType getType() {
91+
DiagnosticsType diagnosticsType = DiagnosticsType.getCommand(type);
92+
if (diagnosticsType == null) {
93+
throw new IllegalArgumentException(type + " Is not a valid diagnostics command type. ");
94+
}
95+
return diagnosticsType;
96+
}
97+
98+
public String getOptionalArguments() {
99+
return optionalArguments;
100+
}
101+
102+
/////////////////////////////////////////////////////
103+
/////////////////// Implementation //////////////////
104+
/////////////////////////////////////////////////////
105+
@Override
106+
public String getCommandName() {
107+
return APINAME.toLowerCase() + BaseCmd.RESPONSE_SUFFIX;
108+
}
109+
110+
@Override
111+
public long getEntityOwnerId() {
112+
Account account = CallContext.current().getCallingAccount();
113+
if (account != null) {
114+
return account.getId();
115+
}
116+
return Account.ACCOUNT_ID_SYSTEM;
117+
}
118+
119+
@Override
120+
public void execute() throws ResourceUnavailableException, InsufficientCapacityException, ServerApiException {
121+
RunDiagnosticsResponse response = new RunDiagnosticsResponse();
122+
try {
123+
final Map<String, String> answerMap = diagnosticsService.runDiagnosticsCommand(this);
124+
if (CollectionUtils.isNotEmpty(Collections.singleton(answerMap))) {
125+
response.setStdout(answerMap.get(ApiConstants.STDOUT));
126+
response.setStderr(answerMap.get(ApiConstants.STDERR));
127+
response.setExitCode(answerMap.get(ApiConstants.EXITCODE));
128+
response.setObjectName("diagnostics");
129+
response.setResponseName(getCommandName());
130+
this.setResponseObject(response);
131+
}
132+
} catch (final ServerApiException e) {
133+
throw new ServerApiException(ApiErrorCode.INTERNAL_ERROR, e.getMessage());
134+
}
135+
}
136+
}

‎api/src/main/java/org/apache/cloudstack/api/response/RunDiagnosticsResponse.java‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
//
2+
// Licensed to the Apache Software Foundation (ASF) under one
3+
// or more contributor license agreements. See the NOTICE file
4+
// distributed with this work for additional information
5+
// regarding copyright ownership. The ASF licenses this file
6+
// to you under the Apache License, Version 2.0 (the
7+
// "License"); you may not use this file except in compliance
8+
// with the License. You may obtain a copy of the License at
9+
//
10+
// http://www.apache.org/licenses/LICENSE-2.0
11+
//
12+
// Unless required by applicable law or agreed to in writing,
13+
// software distributed under the License is distributed on an
14+
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
// KIND, either express or implied. See the License for the
16+
// specific language governing permissions and limitations
17+
// under the License.
18+
//
19+
20+
package org.apache.cloudstack.api.response;
21+
22+
import com.cloud.serializer.Param;
23+
import com.cloud.vm.VirtualMachine;
24+
import com.google.gson.annotations.SerializedName;
25+
import org.apache.cloudstack.api.ApiConstants;
26+
import org.apache.cloudstack.api.BaseResponse;
27+
import org.apache.cloudstack.api.EntityReference;
28+
29+
@EntityReference(value = VirtualMachine.class)
30+
public class RunDiagnosticsResponse extends BaseResponse {
31+
@SerializedName(ApiConstants.STDOUT)
32+
@Param(description = "the standard output from the command execution")
33+
private String stdout;
34+
35+
@SerializedName(ApiConstants.STDERR)
36+
@Param(description = "the standard error output from the command execution")
37+
private String stderr;
38+
39+
@SerializedName(ApiConstants.EXITCODE)
40+
@Param(description = "the command execution return code")
41+
private String exitCode;
42+
43+
public String getStdout() {
44+
return stdout;
45+
}
46+
47+
public void setStdout(String stdout) {
48+
this.stdout = stdout;
49+
}
50+
51+
public String getStderr() {
52+
return stderr;
53+
}
54+
55+
public void setStderr(String stderr) {
56+
this.stderr = stderr;
57+
}
58+
59+
public String getExitCode() {
60+
return exitCode;
61+
}
62+
63+
public void setExitCode(String exitCode) {
64+
this.exitCode = exitCode;
65+
}
66+
67+
}

‎api/src/main/java/org/apache/cloudstack/diagnostics/DiagnosticsService.java‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
//
2+
// Licensed to the Apache Software Foundation (ASF) under one
3+
// or more contributor license agreements. See the NOTICE file
4+
// distributed with this work for additional information
5+
// regarding copyright ownership. The ASF licenses this file
6+
// to you under the Apache License, Version 2.0 (the
7+
// "License"); you may not use this file except in compliance
8+
// with the License. You may obtain a copy of the License at
9+
//
10+
// http://www.apache.org/licenses/LICENSE-2.0
11+
//
12+
// Unless required by applicable law or agreed to in writing,
13+
// software distributed under the License is distributed on an
14+
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
// KIND, either express or implied. See the License for the
16+
// specific language governing permissions and limitations
17+
// under the License.
18+
//
19+
package org.apache.cloudstack.diagnostics;
20+
21+
import org.apache.cloudstack.api.command.admin.diagnostics.RunDiagnosticsCmd;
22+
23+
import java.util.Map;
24+
25+
public interface DiagnosticsService {
26+
27+
Map<String, String> runDiagnosticsCommand(RunDiagnosticsCmd cmd);
28+
29+
}

‎api/src/main/java/org/apache/cloudstack/diagnostics/DiagnosticsType.java‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
//
2+
// Licensed to the Apache Software Foundation (ASF) under one
3+
// or more contributor license agreements. See the NOTICE file
4+
// distributed with this work for additional information
5+
// regarding copyright ownership. The ASF licenses this file
6+
// to you under the Apache License, Version 2.0 (the
7+
// "License"); you may not use this file except in compliance
8+
// with the License. You may obtain a copy of the License at
9+
//
10+
// http://www.apache.org/licenses/LICENSE-2.0
11+
//
12+
// Unless required by applicable law or agreed to in writing,
13+
// software distributed under the License is distributed on an
14+
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
// KIND, either express or implied. See the License for the
16+
// specific language governing permissions and limitations
17+
// under the License.
18+
//
19+
package org.apache.cloudstack.diagnostics;
20+
21+
public enum DiagnosticsType {
22+
PING("ping"), TRACEROUTE("traceroute"), ARPING("arping");
23+
24+
private String value;
25+
26+
DiagnosticsType(String value) {
27+
this.value = value;
28+
}
29+
30+
public String getValue() {
31+
return value;
32+
}
33+
34+
public static DiagnosticsType getCommand(String cmd) {
35+
for (DiagnosticsType type : DiagnosticsType.values()) {
36+
if (type.value.equalsIgnoreCase(cmd)) {
37+
return type;
38+
}
39+
}
40+
return null;
41+
}
42+
}

‎core/src/main/java/com/cloud/agent/resource/virtualnetwork/VRScripts.java‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,4 +69,5 @@ public class VRScripts {
6969

7070
public static final String VR_CFG = "vr_cfg.sh";
7171

72+
public static final String DIAGNOSTICS = "diagnostics.py";
7273
}

‎core/src/main/java/com/cloud/agent/resource/virtualnetwork/VirtualRoutingResource.java‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,9 @@
2222
import java.io.IOException;
2323
import java.net.InetSocketAddress;
2424
import java.nio.channels.SocketChannel;
25+
26+
import org.apache.cloudstack.diagnostics.DiagnosticsAnswer;
27+
import org.apache.cloudstack.diagnostics.DiagnosticsCommand;
2528
import org.joda.time.Duration;
2629
import java.util.ArrayList;
2730
import java.util.HashMap;
@@ -189,9 +192,11 @@ private Answer executeQueryCommand(NetworkElementCommand cmd) {
189192
} else if (cmd instanceof GetDomRVersionCmd) {
190193
return execute((GetDomRVersionCmd)cmd);
191194
} else if (cmd instanceof CheckS2SVpnConnectionsCommand) {
192-
return execute((CheckS2SVpnConnectionsCommand) cmd);
195+
return execute((CheckS2SVpnConnectionsCommand)cmd);
193196
} else if (cmd instanceof GetRouterAlertsCommand) {
194197
return execute((GetRouterAlertsCommand)cmd);
198+
} else if (cmd instanceof DiagnosticsCommand) {
199+
return execute((DiagnosticsCommand)cmd);
195200
} else {
196201
s_logger.error("Unknown query command in VirtualRoutingResource!");
197202
return Answer.createUnsupportedCommandAnswer(cmd);
@@ -292,6 +297,15 @@ private Answer execute(CheckRouterCommand cmd) {
292297
return new CheckRouterAnswer(cmd, result.getDetails(), true);
293298
}
294299

300+
private Answer execute(DiagnosticsCommand cmd) {
301+
_eachTimeout = Duration.standardSeconds(NumbersUtil.parseInt("60", 60));
302+
final ExecutionResult result = _vrDeployer.executeInVR(cmd.getRouterAccessIp(), VRScripts.DIAGNOSTICS, cmd.getSrciptArguments(), _eachTimeout);
303+
if (!result.isSuccess()) {
304+
return new DiagnosticsAnswer(cmd, false, result.getDetails());
305+
}
306+
return new DiagnosticsAnswer(cmd, result.isSuccess(), result.getDetails());
307+
}
308+
295309
private Answer execute(GetDomRVersionCmd cmd) {
296310
final ExecutionResult result = _vrDeployer.executeInVR(cmd.getRouterAccessIp(), VRScripts.VERSION, null);
297311
if (!result.isSuccess()) {
@@ -454,6 +468,6 @@ private Answer execute(AggregationControlCommand cmd) {
454468
_vrAggregateCommandsSet.remove(routerName);
455469
}
456470
}
457-
return new Answer(cmd, false, "Fail to recongize aggregation action " + action.toString());
471+
return new Answer(cmd, false, "Fail to recognize aggregation action " + action.toString());
458472
}
459473
}

0 commit comments

Comments
 (0)