Acerca de las consultas

En este documento, se describen los componentes de una consulta de App Topology y la sintaxis de la consulta.

Componentes de la consulta

Las consultas de App Topology constan de varios componentes:

  • Nodos: Recursos descubiertos Google Cloud o registrados en App Hub o Agent Registry. Estos son algunos ejemplos de nodos:

    • Una VM de Compute Engine
    • Una imagen de contenedor en Artifact Registry
    • Un agente
    • Una alerta de Cloud Monitoring
    • Una aplicación, un servicio o una carga de trabajo de App Hub
    • Una vulnerabilidad

    Los recursos que puedes consultar dependen del dominio que elijas. El dominio SRE incluye todos los recursos compatibles.

  • Propiedades: Son las propiedades de un nodo que puedes usar para definir mejor una búsqueda. Por ejemplo, puedes consultar una vulnerabilidad con un ID de CVE específico.

  • Borde: Es una relación direccional entre dos nodos.

Estructura de la consulta

En esta sección, se proporciona una descripción general de la estructura de la consulta. Para obtener más detalles, consulta la documentación de referencia de la herramienta generate_discovered_resources_topology.

Las consultas usan la sintaxis de filtrado de AIP-160.

Entre los elementos clave de una búsqueda, se incluyen los siguientes:

  • Las consultas comienzan con un startingNode que especifica un nodo raíz.
  • Las relaciones con el startingNode raíz se definen con neighbor. El elemento neighbor define nodos y bordes conectados.
  • LabelPropertiesPattern especifica expresiones de coincidencia.
    • label_matcher_expr: Es una expresión de coincidencia para las etiquetas de nodos o aristas.
    • property_matcher_expr: Es una expresión de coincidencia para filtrar propiedades específicas de un nodo o borde.
  • Puedes definir una relación direccional con el campo direction.

En el siguiente ejemplo, se muestra una consulta para las alertas asociadas con la carga de trabajo de App Hub foo en el proyecto web-project. También muestra el uso de alias para etiquetar nodos, de modo que sea más fácil hacer referencia a ellos en expresiones posteriores.

{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
  "name": "generate_discovered_resource_topology",
  "arguments": {
    "name": "projects/web-project/locations/global/discoveredResourcesTopology",
    "topologyDomains": ["projects/web-project/locations/global/domains/SRE"],
    "filter": {
        "startingNode": {
        "alias": "source",
        "labelPropertiesPattern": {
          "labelMatcherExpr": "Base/apphub.googleapis.com/Workload",
          "propertyMatcherExpr": "source.Base/app/workloadReferenceUri = 'foo'"
        }
      },
      "neighbors": [
          {
          "edge": {
            "labelPropertiesPattern": {
                "labelMatcherExpr": "Observability/HAS_ALERT"
            },
            "direction": "TO"
          },
          "graph": {
              "startingNode": {
              "alias": "alert",
              "labelPropertiesPattern": {
                "labelMatcherExpr": "Observability/Alert"
              }
            }
          }
        }
      ]
    }
  }
},
}

Nodos coincidentes

Especifica los tipos de recursos (nodos) con la expresión de coincidencia label_matcher_expr. Puedes hacer coincidir un solo tipo de nodo o varios tipos.

Un label_matcher_expr puede usar operadores OR o AND, pero no puedes combinar ambos tipos de operadores en una sola expresión de coincidencia.

Ejemplos:

  • Cargas de trabajo de App Hub coincidentes: "Base/apphub.googleapis.com/Workload"
  • Coincide con las cargas de trabajo o los servicios descubiertos: "Base/DiscoveredWorkload OR Base/DiscoveredService"

Propiedades de coincidencia

Filtra los atributos de un nodo con la expresión de coincidencia property_matcher_expr.

Existen dos tipos de propiedades:

  • Propiedades del sistema integradas: Son propiedades que se aplican a todos los nodos y aristas:
    • Para nodos: NodeName (para nodos)
    • Para los bordes: EdgeName (para los bordes)

  • Etiquetas: Es la lista de etiquetas en un nodo o borde que se pueden usar con expresiones de filtro de propiedad. Por ejemplo:

    (CONTAINS_ANY(alias.Labels, "Base/MCPServer") AND alias.Base/agentregistry/urn = "foo") OR (CONTAINS_ANY(alias.Labels, "Base/Agent") AND alias.Base/agent/framework = "bar")

  • Propiedades del esquema de dominio: Son las propiedades específicas de un tipo de recurso, como Base/location, Observability/errorRate y Base/app/state. El método GetSchema devuelve estas propiedades.

    Por ejemplo, para filtrar un recurso con la etiqueta n en la región us-central1, usa la expresión n.Base/location = "us-central1".

Para obtener una lista de los operadores admitidos en las expresiones de coincidencia de propiedades, consulta LabelPropertiesPattern.

Indicaciones de navegación perimetrales

Para los bordes, edge.direction especifica la dirección, y el valor predeterminado es DIRECTION_UNSPECIFIED. Puedes establecer uno de los siguientes valores para indicar la relación entre el nodo de origen y el nodo de destino.

  • TO: Desde la fuente hasta el destino.
  • FROM: Del destino al origen.
  • ANY: La relación entre los nodos es bidireccional.

Cuando se conoce la dirección, usa TO o FROM. Las búsquedas bidireccionales "ANY" expanden el combinador de estados de recorrido de forma combinatoria y aumentan la latencia de la API.

Limitaciones

Tamaño de la consulta y la topología:

  • Las respuestas a las búsquedas pueden tardar más en devolver resultados si son más complejas. Esto incluye las siguientes condiciones:
    • propertyMatcherExpr incluye más de 4 comparaciones.
    • El recorrido de la topología incluye más de cinco saltos en la ejecución de la consulta.
  • No se admite la paginación para los datos de topología devueltos.
  • La API devuelve un máximo de 1,000 rutas únicas.
  • Para los datos de observabilidad:
    • Los nodos Observability/Alert solo admiten el operador de igualdad (=).
    • Las aristas Observability/SENDS_TRAFFIC no admiten filtros de propiedades.

Disponibilidad de los datos:

  • Google Cloud Observability no admite la telemetría para todos los servicios y cargas de trabajo de App Hub. Para obtener una lista de los recursos de infraestructura compatibles, consulta Infraestructura compatible con el Monitoreo de aplicaciones.
  • Cuando visualizas la topología de una aplicación de App Hub, los recursos que se pueden compartir entre aplicaciones no se incluyen en la visualización.
  • Cuando borras un evento de estadísticas de Developer Connect, es posible que el evento siga apareciendo en los resultados de la consulta de la topología de la app durante unos días.
  • En el caso de los datos de seguridad y cumplimiento proporcionados por Security Command Center, se aplican las siguientes condiciones:
    • Los datos proporcionados están en versión preliminar.
    • Los datos solo están disponibles para los proyectos y las aplicaciones de una organización de Google Cloud.